Fragmented documentation in too many formats in too many places. We have scattered documentation all over the place.. PDF user manual, HTML user manual, PDF reference, HTML reference, txt user manual, TXT reference, offline docs, online docs, docs on lazarus sourceforge page, no fcl-db docs, etc.
Docs Written By One Man?
It is virtually impossible for anyone to update the FPC documentation, except Michael and maybe even the fpc team themselves (it is hard to tell since they live in a cave together and we can't tell what goes on in core).
In order to make changes to the documentation a developer must submit a bug report or send a patch.. which, no one does. Why? Because people are lazy by nature and are not motivated to fire up their MERGE program and send patches for minor or even major documentation updates and fixes.
The fpc online documentation 'add comment' system is a nice try, but it is a failure in its current state. The add comment system is not known by anyone since it is not in the main documentation.. it is optional in a mirror of the docs. i.e. instead of visiting the add comment version of the docs, people don't.. because they have no idea it exists. People land on the non-comment docs through google and such.
Instead of all these different "views" of the FPC docs, they all need to be in one place. Direct people to ONE SET of docs.. not 50 different ones. Or, on each mirror page or each docs site, explicitly state that it is a mirror and include information at the bottom of each page where one can submit fixes to the docs or how to add a comment.
One thing I've learned from over 10 years of internet hacking is that visitors won't make any extra effort.. they are lazy. Currently, the documentation at the bottom of each FPC doc page does not say 'submit a bug report for the docs or add a comment here'.
Forget Online Docs
I've even heard that fpc html docs may be dropped, because the TeX tool doesn't create good HTML docs, and other problems. PDF may be the only documentation available for FPC, at some point.
The problem with PDF is that it is not very well indexed by google. Nor is PDF very accessible for end users using search engines, even if google points to pdf file links in the search results. People are not looking for PDF when they use google to find quick information on freepascal. People are looking for quick loading HTML pages that offer them instant gratification and instant help.
Having HTML docs indexed by Google is important.. even if it costs server bandwidth. Having a web presence is important. The PHP manual figured out that a long time ago.
I'm beginning to think that Z505 should just forget the idea of freepascal doing the online documentation right.. They just aren't experts there. They don't know what they are doing when it comes to "web marketing" and "collaborative documentation" efforts. I will pay for the server bandwidth of LUFDOC and the fpc team can do whatever they want with their PDF files and LaTeX stuff. The server bandwidth for a documentation system is a non issue for me, considering that the hosting bill for ALL my websites right now is $5-$10/month, and I am not just running LUFDOC but several other services. This is because I don't over architect my web programs with technology that does require you have a special server setup.
If the traffic gets to be more than it is now, I will simply be making enough money from my other services and consulting that a $20 or $30 per month fee will not be an issue to run lufdoc and all my other stuff, such as my 5 million row database wikipedia mirror.
The server bandwidth and cost issues is another thing that fpc team doesn't understand: funding, consulting, donations. You don't have to make FPC into a commercial compiler, but you could at least accept donations so that your server bill can be paid off without constant bitching about the fpc project just being a hobby, and bitching about how there is no money for a proper documentation comment system due to the server bandwidth issue. That is a straw man argument since there is other stuff on the fpc website costing much more bandwidth which could be conserved: FPC downloads could be directed to sourceforge, simtel, and mirrors only. I.e. if no large 80MB fpc downloads and snapshots were stored on the fpc servers, this would save much more bandwidth.
FCL-DB/sqldb Not Documented
SQLDB or FCL-DB were not documented as of year 2007.
So what did Powtils hackers do?
It started in Lufdoc where tidbits of information on SQL db were available. Discussion in PasForum and on Leonardo's blog triggered Leonardo and I to start documenting sqldb/fcl-db. Jorge was asking a question on Leonardo's blog too, regarding how to use FLC-DB.
When we mentioned it to the FPC mailing list that we started the SQLDB/FCL-DB docs, people negatively reacted. They complained and bitched about how we should have thrown it up on some disorganized wiki page (the fpc wiki) instead of what we did over at LUFDOC. Or there was bitching that we should have just made a patch.
Earth to humans: a documentation system is not a fucking one time "patch". It is a collaborative effort that takes incremental changes and daily refinement. No one is going to submit "daily patches" or "weekly patches" for documentation. Imagine 5 developers or 10 developers all fucking around with their winmerge tools, sending a bunch of unsynchronized broken patches of the documentation in for review to who knows who. Nor is anyone going to have the motivation to do a documentation patch in the first place, even if they are superman.
Patching Docs: Not Right
In the early stages of a documentation project, it is essential for it NOT TO BE submitted as a big once off "patch". In the later stages of documentation, it also isn't good to require people to send patches. In fact, it is never good to have a patch system in place if there are proper alternatives that make collaborative documentation editing easy.
Patches are hard.. they are tough. Things need to be easy. I'm an experienced and seasoned developer myself, and every time I think about a "patch" I get this motivation killer feeling inside of me.. if I can't do it, who can? Ego's aside, I'm serious.. if I fear patches, who will enjoy them?
Docs aren't something you let the community do with WinMerge, for fuck sake. If the community enjoyed doing such things you'd see 52 fpc bug reports each day with documentation patches (all unsynchronized) attached. It won't happen, ever. Plus, the guy who has to implement the patch has the motivation killing feeling hit him when he realizes its more work and more fucking around for him to do.
That's why currently it takes about 5 months or 2 years for even minor issues in FPC documentation to get fixed.
Bottom Line
What bothers me is not the fact that the current FPC documentation system needs improvement. Rather more painfully, what bothers me is that any time I make a suggestion for improvement, pretty much all my ideas are negatively put away. Don't need that, don't want that, couldn't possibly help the project, not going to be effective, server bandwidth will hurt us if we do it that way, send patches if you want changes seen in the docs, blah blah blah.
If something is a piece of shit in its current state and the developers are willing to improve it but don't have the time, then that is fine. Then one could say "this needs to be improved but we are lacking time". But this is not the case with the fpc doc system. All suggestions I've made for it to be improved have been nay-sayed and/or ignored even if the suggestions are good ones.
All suggestions for improving the contributed units section are naysayed and put down too." Don't need any more sections, just put the stuff in the fpc wiki". "Send us a patch if you want it fixed". Hmm, and how pray tell does one work on a patch, if the idea is not going to be accepted in as a patch anyway? First one must communicate before he works on a patch, if a patch is even the most brilliant method of delivery in the first place. (my method of delivery is saying "fuck the FPC website and the FPC team, I'll do it on my own domain name here at Z505").
Whatever happened to structure? Me thinks people should learn about Records and Structs. Throwing shit into a media wiki and having everyone send unsynchronized patches for a documentation system is not structure. The sloppiest language in the world, PHP, has better structure when it comes to community and documentation collaboration.
Why don't I run my own doc system if I have so many ideas?
Well I am running my own doc system. That isn't the problem. The problem is that even discussing an idea, feature, or suggestion before coding it is not any fun on the fpc mailing lists. I just code stuff for myself and for my consulting clients now.. no more fun development for and with the FPC team, because developing or suggesting stuff to FPC team is NEVER fun. They make it basically so difficult to discuss something that I've given up.. and all my efforts will go into my clients and into my own websites.
Hey.. but just throw the page up on the fpc media wiki since that seems to be the solution to every problem. And remember to send a patch.
|
