<html><body><blockquote style="margin:0 0 0 40px;border:none;padding:0px;"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>----- Original Message -----</div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div style="width:auto;background-color:rgb(228,228,228);"><div style="font-weight:bold;">From:</div> "Tim Ansell" <mithro@mithis.com></div></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div style="font-weight:bold;">Sent:</div>Tue, 18 Jun 2013 08:56:03 +1000</div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br /></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br /></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>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.</div></div></div></div></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br /></div></div></div></div></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>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.</div></div></div></div></div></div></div></div></blockquote><br />I suspect you mean 'can't instil' :-)<br /><blockquote style="margin:0 0 0 40px;border:none;padding:0px;"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br /></div></div></div></div></div></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>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.</div></div></div></div></div></div></div></div></div></blockquote><br />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.<br /><br />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.<br /><br />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.<br /><br /><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div>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.</div></div><div><br /></div><div>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.</div><div><br /></div><div>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.</div><div><br /></div><div>Hope this helps,</div><div><br /></div><div>Paul</div></div></div></div></body></html>