[geeklog-devel] Wiki docs

[Rob Griffiths]

On Jul 11, 2007, at 5:15 PM, Oliver Spiesshofer wrote:

> I guess the number of words is the trigger here. We simply pay by  
> word, and simply say that the text has to increase the  
> understanding of the user/developer about the functions described.

As a potential user of the wiki (and possibly a writer for some  
sections), I think paying by the word sends the wrong message: you'll  
wind up with overly-winded explanations of simple features. At some  
point, some judgement call is going to be required from the Geeklog  
developers -- someone on the team must make a decision as to how well  
a feature has been explained, and you'll be reading *lots* of words  
for nearly every section.

Without a review step of some sort, and a focus on paying by the  
word, I'm afraid of what you might wind up with: hugely wordy  
descriptions of setting the geeklog.conf path in common.html, for  
instance. Here's an alternative thought:

Rank the 'difficulty' (in advance) of each section of the wiki that  
needs to be worked on, and assign dollar values based on difficulty.  
Easy write-ups are worth $1x, medium is $1.5x, and tough is $3x (or  
whatever). Finished sections are reviewed by someone on the Geeklog  
team, and if they are deemed to be acceptable, the bounty is paid.  
This should drive writers to write the fewest words possible to  
adequately describe a given feature, as they don't make more money by  
writing longer entries.

As a guideline for writers, you could establish a recommendation for  
each difficulty level. An easy section will typically require less  
than 500 words and one screenshot; medium is 1,000 and three; and  
hard is 2,000 or more and five screenshots (again, whatever you  
want). Giving a writer a target will also help keep word count  
inflation to a minimum.

Feel free to ignore these suggestions, but as someone who writes for  
a living, I think paying an increasing amount for more words written  
isn't going to help you get truly useful documentation. You'll have  
long documentation, yes, but it may not be all that good.

Just my $0.02...

-rob.