[Desktop_architects] Documentation accumulation (was Re: What is your answer to solve the top inhibitor for the Linuxdesktop adoption?)

[Kurt Pfeifle]

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