On Wednesday 04 January 2006 07:33, Bryce Harrington wrote: > 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.
This is my impression of the Inkscape project too, as an "outsider" to it. And it pays.... ;-) FWIW, the Scribus folks are doing the same thing in a way, and it pays there too. Their documentation also is excellent. (Possibly also due to the very active criss-cross-fertilisation and cooperation of the Scribus and Inkscape developers..) > 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 </AOL> Cheers, Kurt
_______________________________________________ Desktop_architects mailing list [email protected] https://lists.osdl.org/mailman/listinfo/desktop_architects
