On Tue, Jan 03, 2006 at 09:55:41PM -0700, Aaron J. Seigo wrote:
> maybe i'm just very jaded by watching to date how documentation doesn't
> accumulate in projects very effectively.
This is very true. The vast majority of projects I've been in have had
this documentation gap issue.
Inkscape's been a pleasant exception, and here's why I think it avoided
the problem:
When we started, Inkscape had hardly any documentation. Even though we
were forking from a project that'd been around for 3 years, none of the
developers had much interest in writing documentation, so no one did.
At the outset, we very deliberately elevated the value we gave to
documentation writers to be on par with the coders. In effect, we
consider documenters to be full fledged developers just like people who
only code. Sometimes I think that in open source projects documentation
is considered a chore, but if you define it to be a key development
activity that one can gain as much recognition from as fixing a bug or
adding a little feature, there can be a lot of motivation to do it.
I think it also helps a lot that our primary documentation - a set of
tutorials under the Help menu - are done in Inkscape itself. Also,
since they're written as tutorials instead of as a reference guide,
they're much more enjoyable to read through (plus the examples can be
manipulated directly). Everyone knows the tutorials are cool and get
lots of user attention, so people just naturally put a high importance
on making sure they're kept up to date as new features are added.
So I think the key take away points from this experience are:
* Elevate the value of people who contribute documentation
* Define this documentation writing to be of key importance to the
success of Linux.
* Position this documentation so it is extremely highly visible to
our entire target audience. If they have to get to it via google,
that's not good enough.
* Make the documentation both exactly what the user needs, plus
fairly enjoyable to read. I.e., give it a lot of intrinsic value.
* Make it straightforward for others to get involved with editing,
adding, translating, and republishing the documentation.
Bryce
_______________________________________________
Desktop_architects mailing list
Desktop_architects@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/desktop_architects
