[Video] Power of documentation verse Software "which does the right thing"

[Paul Wayper]

----- Original Message -----From: "Tim Ansell" Sent:Tue, 18 Jun 2013
08:56:03 +1000

What do other people think of the DVSwitch documentation? I think it's
pretty good compared to many projects and there is quite a few "here
is how I did it" stories out on the net.
I feel that doing video capture can only really be learned by doing,
even the best documentation can instill how important having things
like spare power plugs available until you've found that you need it.
I suspect you mean 'can't instil' :-)

The other thing I'd like to bring up is that very few people actually
read the documentation and it's much better for the software to "just
do the right thing". This is something I've been trying to do with the
portable system. It automatically selects the right settings unless it
needs a human to do something, then it displays a helpful page with
pictures and explanation on what to do. More importantly, it won't let
the person move forward until they have successfully fix the issue
that is being reported. IE Actually plug in the power. Obviously this
is limited to simple cases, I doubt we'll ever be at that point with
conference recording - but just food for thought.
On the one hand, IMO documenting a system is a really good chance to
have a long hard think about your system.  Does your explanation of a
feature seem to be complicated or confusing?  Maybe the feature
itself is the problem!  Does it take a lot of steps to explain how to
do one particular thing?  Maybe you need to make that task simpler!
 Does your documentation describe exactly how you actually work with
it and not the overall process?  Then you're too involved in the
software and need to try and explain it to someone else.

On the other hand, documentation isn't just about writing "Use the
File -> Open menu command to open a file".  It's about having the
quick start guide, the tutorial, the reference manual, the
troubleshooting guide, and the procedure guide - i.e. that you have a
range of different documentation that describes the system in
different ways.  If you're repeating exactly what's on the screen,
then you're doing it wrong.  If you're writing a whole bunch of bash
commands in your documentation, then you should be writing a bash
script.

So I definitely agree that software should try to reduce the need for
the user to perform a whole bunch of steps from the manual.  As your
portable system demonstrates, Tim, the software (and hardware) should
make it easy for the user to know what comes next and what they need
to do.

However, I remember your demo of that system in 2012, Tim.  And I
think it ably demonstrated that people react in a variety of ways and
the software cannot anticipate them all.  Nor can it hope to lead
them on the One True Path from A to Z and prevent them from going to G
when they haven't passed through F yet.  Yes, it worked, but I
remember the confusion on the volunteer's face when he was trying to
work out where to look next for instructions.
I think in this context we also have to remember that it's not just
documenting the software; we really need to document the equipment,
the process and (especially) the troubleshooting.  Knowing that
getting a low hum on the audio circuit probably means a ground loop -
and how to fix that - is very useful.  And that is difficult too,
because there's a lot of just plain experiential knowledge that is
hard to define precisely.
Anyway, I think we should keep our sights on a reasonable goal.  It
might be a good idea to start with a section on the LA wiki that we
can document the equipment set-up for LCA.
Hope this helps,
Paul
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.linux.org.au/pipermail/video/attachments/20130618/f7ed16e0/attachment-0001.htm