LWN.net Logo

User manuals for free software

User manuals for free software

Posted Sep 25, 2008 4:12 UTC (Thu) by tnoo (subscriber, #20427)
In reply to: User manuals for free software by flewellyn
Parent article: User manuals for free software

Django has excellent documentation, that seems to be written together with the
code.


(Log in to post comments)

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 (guest, #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? ;)

Copyright © 2013, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds