Things People Hate about Your Open Source Docs
blog.smartbear.com
Things People Hate about Your Open Source Docs
1–10 of 37 posts
Re: Things People Hate about Your Open Source Docs
#2Very good thoughts. At least there should be a README. I think about creating a template for READMEs.
Re: Things People Hate about Your Open Source Docs
#3Manpages used to be the defacto best source of information, but sometime in the last 15 years they went from great to a hit and miss shambles.
I write this up to GNU's "info" being preferred by some programs, but then that not being installed properly or at all on many system, and people hating manpage syntax, often with good reason.
That said, some systems pay a lot of attention to this. OpenBSD's mandoc is a great example of a modernization of the manpage system, and their manpages are second to none: http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html
Re: Things People Hate about Your Open Source Docs
#4Very good thoughts. At least there should be a README. I think about creating a template for READMEs.
That would be a good open source project!
Re: Things People Hate about Your Open Source Docs
#5Very good thoughts. At least there should be a README. I think about creating a template for READMEs.
That would be a good open source project!
This project sounds sort of promising: https://github.com/bevry/readme-utils
Re: Things People Hate about Your Open Source Docs
#6Very good thoughts. At least there should be a README. I think about creating a template for READMEs.
I like to create README files that are also shell scripts that perform some of the actions the README says you need to do to build/run whatever it is I'm writing about.
Re: Things People Hate about Your Open Source Docs
#7Of course, your examples shouldn’t just be brief two-line snippets. As Rich Bowen of the Apache project puts it, “One correct, functional, tested, commented example trumps a page of prose, every time.”
If HN allowed signatures, that quote would be mine. I grok libraries and other people's code so much faster when I have a good working example, and the mere existence of that example makes me 10x more likely to use the lib (or, when I have no other option, 10x more likely to complain less).
Re: Things People Hate about Your Open Source Docs
#8Lack of examples is the major problem, since it is hard to maintain examples in sync with the code. I created tool https://npmjs.org/package/xplain that transforms unit tests (javascript) into human readable examples in the API docs. Makes lots of up-to-date examples in the docs possible without any penalty.
Re: Things People Hate about Your Open Source Docs
#9Having offline docs can be quite handy. A few years ago a friend and I put together an iOS app called iCPAN, so that we could have offline Perl docs at our disposal. This kind of thing is particularly helpful because perldoc doesn't work on modules which you have not yet installed. It's also great if you want to read Perl docs on the subway, but I'll admit that's not everyone's cup of tea. :)
Re: Things People Hate about Your Open Source Docs
#10The great thing about open source documentation is that you can write a patch and attempt to fix it. It would probably take less time to clone a repository and submit a pull request than it did for the author to write that article.