Advertisement
Front, Kernel, Security, Distributions, Development. See your byline here on LWN.net.
| |||||||||||||
|
| |||||||||||||
User manuals for free softwareUser manuals for free softwarePosted Sep 25, 2008 3:31 UTC (Thu) by flewellyn (subscriber, #5047)Parent article: User manuals for free software As a model for how a good manual should be written and organized, I think the PostgreSQL manuals would be perfect. I have yet to find a free software project which had better documentation; the manuals for the whole system are comprehensive, approachable, easily read and understood, with clear explanations and examples. It's simply the best documentation for any software system, free or proprietary, that I've yet read.
(Log in to post comments)
User manuals for free software Posted Sep 25, 2008 4:12 UTC (Thu) by tnoo (subscriber, #20427) [Link]
Django has excellent documentation, that seems to be written together with the
code.
Linux technology reference: Posted Sep 25, 2008 4:23 UTC (Thu) by constantine (guest, #53664) [Link]
http://www.makelinux.net/reference
is attempt to collect and organize all existed Linux and FOSS documentation to single knowledge tree. Your comments are welcome.
User manuals for free software Posted Sep 25, 2008 13:51 UTC (Thu) by sbergman27 (subscriber, #10767) [Link]
I was going to mention Django but you beat me to it. Actually, my whole Django development stack (Django, Python, PostGreSQL, JQuery) has ecxellent documentation through and through, and I can concentrate on doing my work. Unlike certain other development environments I've used where I spent more time mucking around trying to figure out how some api call is supposed to work based on a sketchy user-provided example use-case from a previous release on a poorly maintained wiki... as the devs, who felt that writing documentation was below their station, talked amongst themselves about how cool release x+1 was going to be. That framework has all but tanked as Django flourishes.
Good documentation is one of the hallmarks of a successful project. And in my experience, if the quality of the documentation is poor early on in the project, it stays that way, no matter how much lip-service gets paid to improving it on the mailing list. Users should not waste too much time waiting and hoping that a poorly documented product will get better. Making a clean break and finding something else usually saves *much* time and frustration in the long run.
User manuals for free software Posted Sep 25, 2008 23:47 UTC (Thu) by giraffedata (subscriber, #1954) [Link] as the devs, who felt that writing documentation was below their station, talked amongst themselves about how cool release x+1 was going to be. I don't think they felt writing documentation was below their station; they felt it was boring. As they get paid the same to do boring writing as to design and code the cool new release, the choice is obvious.
User manuals for free software Posted Oct 2, 2008 3:53 UTC (Thu) by dirtyepic (subscriber, #30178) [Link]
And answering the same question about some underdocumented piece of the API for the twenty-first time this month is less boring? ;)
User manuals for free software Posted Sep 25, 2008 7:38 UTC (Thu) by DonDiego (subscriber, #24141) [Link]
I'm very happy with the documentation of Subversion, which was inspired by the excellent documentation for CVS, and has in turn inspired the documentation for Mercurial.
User manuals for free software Posted Sep 25, 2008 7:46 UTC (Thu) by ca9mbu (guest, #11098) [Link] I would also highly recommend the documentation for SQLAlchemy. It's clear, well structured and accurate.
|
|
||||||||||||