The Few, the Tired, the Open Source Coders

[Thorsten]

The ALS documentation is invaluable to aircraft effects modelers, at least this one! (...) The novel you wrote for the Shuttle is, for those that need it, irreplaceable without becoming an astronaut and reading through volumes of technical data as you did.

But these are just two examples of having to expect to explain the same thing over and over again It is reasonably clear that pretty much 'every' aircraft maintainer would want to know how to properly implement ALS goodies, or that everyone who wants to fly the Shuttle asks the same question - so these are areas where we can expect dozens (or in the latter case hundreds) of readers - makes it worthwhile.

But should I document e.g. the way the Shuttle ADI ball is done? Or the way ALS does the upper edge of a fog field? Perhaps people will tinker with that as well - perhaps not - but the expected number of readers is 0-1 or so.

And in the first case - just observe how many people do not read the Shuttle documentation and just ask anyway...

The point is not that it's a waste of time to document anything - the point is that there's some cost/benefit analysis involved, and the more technical the problem is, the less useful it is to try to document it up-front.

[Hooray]

That's actually a fact - I have repeatedly written tutorials at the request of end-users on the forum - but that has rarely translated into any tangible/visible results in the short term.
For many such tutorials it took literally months or even years until someone showed up and really benefited from such materials.

Time has shown over and over again that many of the people who originally encourage others to write docs, don't really get involved in helping proof-read/update or translate, let alone adopt/maintain such articles or the documented features.

So there really is a pain/gain thing to keep in mind here, like both Stuart and Thorsten said.

For instance, one of the wiki articles that were obviously really popular (based on feedback) was the "Canvas Snippets" article where the idea was to grow a library of copy/paste snippets that people could borrow to get started with Canvas coding. Over the years, many people have expressed their gratitude for the article - still, it's not really been "adopted" by many others, i.e. while there are literally dozens of people who clearly borrow code snippets from that article, there are not really many contributors to add their own snippets: http://wiki.flightgear.org/Canvas_Snippets

In other words, writing documentation from scratch rarely pays off for the people writing/maintaining the documentation (unfortunately).

Ironically, that also explains why copying useful responses from the forum/devel list over to the wiki to improve our documentation, has a better pain/gain ratio in comparison

[frtps]

Well, no.

I used to think that and dumped lots of time into documenting things - with the only result that this was time I did not have creating things. What did not materialize was that people used this documentation.

You are not necessarily aware of the people who refer to the documentation and are satisfied. I had the Regional Texturing wiki page permanently open as a browser tab for many months. It is a superb reference and can be used as a shorthand answer to somebody's question, you simply refer them to it.

[Hooray]

That's certainly true, i.e. there is no obvious/immediate gratification when it comes to creating/updating documentation (usally) - I guess the situation might be a little different with the shuttle ops manual, since that has to be explicitly requested - so that you get at least /some/ feedback about the number of people using that.

However, writing a README file or creating a wiki article is a rather "lonely" effort in comparison - people rarely report back whether they found it useful, sometimes it literally takes months or years to see if the time spent creating something was a waste or not ... Thus, creating features -and not documenting them- can be a little more rewarding, in that people actively reach out and answering specific questions is much less hypothetical than creating documentation without anybody asking for it ...