[fpc-pascal] State of FPC docs.rant

[John]

On 26/04/2010 8:23 AM, Joseph Montanez wrote:
> <snip>
>> I would suggest you checkout the latest copy of the documentation
>> SubVersion repository:
>>
>>   http://svn.freepascal.org/svn/fpcdocs/trunk
>>
>> Then submit code examples for the various units.
>>      
> Are you seriously want everyone that wants to help out be forced into
> SVN and learn FPDoc syntax, submit patches, wait for integration? I'll
> be more then happy to move my work onto Free Pascal Wiki, but I think
> its a bad idea to funnel anyone that wants to add to docs even if its
> a typo change into that sort of process. At least in a wiki if someone
> wanted to make a quick change they could sign in and make it.
> <snip>
>    
On the one hand, Graeme is probably right, in that putting it in the 
docs is the *best* thing to do.  On the other hand, Joseph has a point - 
I have worked out most bits of  FPC over the course of a few years, but 
the documentation system is certainly a notable exception.  After 
several reasonably serious attempts to understand it, I still have not 
got the faintest notion *.

However, I do really agree that the last thing to do is to put it on yet 
another site.  My suggestion would be to just put it on the Lazarus 
wiki, if you are comfortable with wikis.  I did that with some database 
documentation I wrote, not realising at that stage that it really 
applied to FPC RTL rather than Lazarus.  Not one deleted it, no one - 
sorry, only one person - was rude, and I think a few people have used it 
since.  Significantly,  the people who REALLY need it probably won't 
have worked out that it is technically in the wrong place (under Lazarus 
instead of FPC) because it seems to take most people a little while to 
get the difference sorted out anyway.

* If anything is in need of some user level documentation, it is the 
documentation system it self.  I suspect that all the details are 
documented, but no-one has written the overview, because the people who 
wrote it knew it so well, they did not see the need.  Or perhaps I just 
have not ever found it.

cheers
John Sunderland