Tangent: Documentation developers & support providers in a gift economy [LWN.net]

Tangent: Documentation developers & support providers in a gift economy

Posted Dec 9, 2005 10:22 UTC (Fri) by Duncan (guest, #6647)
In reply to: FOSS.IN: A report by achitnis
Parent article: FOSS.IN: A report

> Little drops of water, Little grains of sand....

Very encouraging to read that report.

Hmm... The rest of this goes off on a tangent that I didn't intend when I
clicked that reply button. <g> However, I think it's worth posting, and
am looking forward to the reaction of others, if any.

As it so happens, I'm sort of in the position of that docs guy, here in
the US. I don't "write developer" very well, but I "read and speak
developer" well enough to get by, and, according to the number of "thanks"
posts to various lists and groups (and places like LWN, as well, thru the
comments) to which I've contributed and continue to contribute, I do
better than many at explaining things.

One thing I've noticed is that even tho the community (of which I consider
myself very much a part) /says/ it has a great need for those doing
documentation, it doesn't always (as in very seldom) do such a good job at
providing the traditionally recognized "gift economy" reward -- community
recognition -- to docs developers, at the same level it provides it to
code developers, and does even worse for those that pitch in daily, day in
and day out, on the various forums and lists.

Don't get me wrong. I'm sure most doing so, myself included, recognize
just as well as most contributor coders do, that they've gotten back far
more than they could ever invest, in just the use and breadth and depth of
FLOSS software available to them, but regardless, we all suffer from the
lack of documentation. Anyway, it remains fairly obvious that those in
the community doing the coding continue to reap the biggest rewards a gift
economy can provide, while those doing the documentation and support
generally get far less. Is it any wonder, then, that the economy tends to
produce more code than it does documentation and support? As long as the
reward structure remains, the relative supply ratio will likely remain as
well. That's just life.

It'd be interesting to see discussion of any proposed solutions?

Duncan

(Log in to post comments)

Tangent: Documentation developers & support providers in a gift economy

Posted Dec 9, 2005 13:50 UTC (Fri) by Petre (guest, #34436) [Link]

Many projects are adopting wikis for their documentation, which is a good thing as it makes contributing easier. But I'm always surprised and disappointed that the articles in those wikis don't usually display the names of the individuals who wrote them (and often don't even have a date, so you can't tell how old an article is). It seems to me that having people's names shown with an article--which should be easy since you usually have to create an ID to create/edit articles--should be standard practice. On top of that, the given wiki should have a page showing tallies of who has contributed what (you could count by number of articles, number of words, etc.) The point is to give recognition to people for creating documentation. Documentation is something that just about anyone can contribute to; offering code usually requires a less common skillset.

I've contributed to the K12LTSP wiki because it's something I believe in. Unfortunately, there is no attribution on that system. I don't care about it for myself; rather, I see it as a way that students could build some credentials for themselves, and then they'd have something to put on a resume: "I have written X public articles on such & such topics, which are used by the public" will be more valuable than "I took such & such a classs." I think the PHP documentation handles this well in that there is the official manual, but each page allows anyone to comment, and people add in all sorts of additional help and ideas.

Tangent: Documentation developers & support providers in a gift economy

Posted Dec 9, 2005 15:14 UTC (Fri) by Baylink (subscriber, #755) [Link]

This seems like an excellent place to stick my head up and prospect for a little help on a nascent project to write a bot to extract DocBook format documentation masters from MediaWiki.

Anyone with any deep background on either side got some free minutes?

This doesn't seem like all *that* hard a project; keeping track of cross references for the second pass is probably the hardest part...

But it seems like it would be a really good approach to leveraging the distributed knowledge capture capabilities of a really good wiki package (and, clearly, I think MW is the best :-) in a fashion that fits in with everyone's favorite target intermediate format these days.

I'm just not a good enough coder to actually pull it off.

...

And if you think "documentor" is a hard seat to fill in the FOSS community... try analyst/designer (which is what I've gotten paid for for the last (cringe) 2 decades).