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

[Tim Ansell]

So, as shown below, Paul brought up the idea of documentation for the
current system and I'd like to get other people's thoughts.

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.

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.

- Tim


> So I thought I'd quickly document what the current state is;
>
>    - TwinPac for VGA capture to DV,
>
>    - Firewire based camera for presenter using DV,
>
>    - Going into DVSwitch (pretty much as described by
>    http://dvswitch.alioth.debian.org/wiki/large_meeting/)
>
>    - veypar is used for conferences to allow quick processing of the
>    large amount of video, splitting into talks and uploading to
>    YouTube/pyvideo/other.
>
>    - Going into Flumotion or Icecast for Live Streaming (least tested)
>
>
> The current setup has been well tested and I believe well understood.
>
> More or less.  My experience was that there were a few people who knew
> about this system, but it wasn't well documented online.  The
> documentation, such as the DVswitch page linked above, is terse,
> non-adaptive and mainly handles the working case.  Unfortunately, I wasn't
> able to speak with the people who really know this system - Ryan and Carl -
> and some of the other people who do know it - Tristan, James Iseppi, Matt
> Franklin, Euan, Liam and others - were only able to help educate me to a
> limited extent.
>
> The thing I think is really important in any system we come up with is
> that it's well documented.  I know that's painful, I know that's boring,
> and I know it takes a lot of time.  But it's essential to being able to
> help other conferences and groups.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.linux.org.au/pipermail/video/attachments/20130618/0aa432c2/attachment.htm