I hate incomplete docs the most. Most OSS developers would agree that if you're adding a feature to a repository, then you should also be adding a test. There should also be an expectation that you should be adding docs, too.
Things People Hate about Your Open Source Docs
11–20 of 37 posts
Re: Things People Hate about Your Open Source Docs
#12Amen. Just amen.
I've worked on at least a couple of open source projects now that have a strong and active core team building everything, and who are talented enough to write great code. But when it's almost time to launch v1.0, the call always goes around: "Who's willing to write the documentation?" And the response is always silence. Documenting just isn't as "fun" as coding, I guess.
But it is, arguably, at least as important if not more, if your goal involves popularity. I recommend open source software projects to groups who are looking for an open source solution, and the ones with an active support community and good documentation, but some sloppy code, win every time over the expertly coded masterpiece that can only really be understood by stepping through the code in a debugger.
Re: Things People Hate about Your Open Source Docs
#13The author forgot 'Stale docs'. Once the docs are written, 'that task is done' and new features or changes aren't documented...
Re: Things People Hate about Your Open Source Docs
#14The 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.
Yes, instead of writing an excellent article that explains some principles that could help hundreds or thousands of open source authors improve their projects, he should have taken the approach of shutting up and fixing every one of those projects himself.
Open source should not be about efficiency! It should be about never pointing out anything wrong unless you're willing to change it yourself! Down with feedback! We hate feedback! We're open source authors and we don't have to take it anymore!
Re: Things People Hate about Your Open Source Docs
#15Manpages 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…
I think people now like documentation in lots of different forms - manpages, HTML, pdf, or introspectable docs like Python docstrings. IPython, for example, has all four of those.
There are systems like Sphinx that let you share content between different formats, but they're not magic bullets. For instance, if I write docs relying on inline links because I'm used to viewing them in HTML, the result won't be great for manpage readers.
Re: Things People Hate about Your Open Source Docs
#16Manpages 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…
Wait, there's programs that use info? o.O
Re: Things People Hate about Your Open Source Docs
#17Of 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…
The Three.js project has really shit documentation for most things, but they have scrupulously-maintained examples for their library which serve to answer most questions.
Re: Things People Hate about Your Open Source Docs
#18It's occurred to individuals smarter than myself that projects rise and fall on the strength of their documentation, almost as much as that of their code.
For example, see Django vs. Turbogears or Pylons.
Documentation matters, a lot, despite its relative unsexyness.
Re: Things People Hate about Your Open Source Docs
#19I think I've seen every imaginable "bar" object have every possible "foo" action performed on it. This is the most frustrating thing I find in example code. Yes, I know your library is generalized and will work with any type of object. Please give me a concrete example of where your library might be useful, so I can easily visualize your library's role in my head. I can generalize it myself, thank you very much.
Re: Things People Hate about Your Open Source Docs
#20Manpages 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…
Wait, there's programs that use info? o.O
Oh yeah. 'man cp' from my Arch Linux machine:
---
SEE ALSO
The full documentation for cp is maintained as a Texinfo manual. If the info and cp programs are properly installed at your site, the command
info coreutils 'cp invocation'
---
I ran that 'info' command and promptly ran the one emacs command I have memorized: C-x C-c
:)