> 5. Lack of screenshots
So many GUI libraries do this and it's always frustrating. If you're a GUI library, when I get to your website, the first thing I see should be a screenshot.
Things People Hate about Your Open Source Docs
21–30 of 37 posts
Re: Things People Hate about Your Open Source Docs
#22Of 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.
Care to give a few examples of where three.js docs are lacking?
Re: Things People Hate about Your Open Source Docs
#23Manpages 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…
The info nav system can be avoided with:
info () { command info "$@" 2>&1 | less; }
Another useful approach is to 'project the document' rather than to 'document the project'. Write the draft documents as part of the specification and development process. Code the project. Finally, edit the docs to match the code.
You get to capture the state of early energy and an over- or top-down view before diving into the code, and will remember to mention details of the design while they are fresh and new, rather than at the end of the coding process, when everything has become so familiar that it all seems trivially obvious.
Re: Things People Hate about Your Open Source Docs
#24Of 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…
This is 100% true. I am constantly frustrated by incomplete code examples in documentation. The one thing in particular that bothers me the most are when Python snippets don't show the import statements.
do_magic(param, other_param)
Where do I import do_magic from?!?!
Re: Things People Hate about Your Open Source Docs
#25Not necessary docs, but what I have been observing in a lot of OSS is an absence of one-liner explaining what the project exactly is; especially ones without descriptive project name.
Good "feature list" would probably help, but it's just a pain when reading through 5 paragraphs down only to find that it's not what I think it is.
Re: Things People Hate about Your Open Source Docs
#26Of 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…
This is 100% true. I am constantly frustrated by incomplete code examples in documentation. The one thing in particular that bothers me the most are when Python snippets don't show the import statements. do_magic(param, other_param) Where do I import do_magic from?!?!
Same thing in Java -- if there's a class named something commonplace like "Transaction" or "Connection", it's going to be pretty critical to understand whose implementation that refers to.
Re: Things People Hate about Your Open Source Docs
#27The biggest sin is not explaining what the project does and the problem that it solves.
I've had people complain to me that no one is using their great open source project. I complain that you don't explain what it does or why its great.
They answer that all you have to do is read the code. I try to diplomatically tell them that there aren't enough hours in anyone's life to read all the code on Github.
The project is not ready to upload if you haven't finished the documentation.
Re: Things People Hate about Your Open Source Docs
#28Earlier quoted context omitted.
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' should give you access to the complete manual. --- I ran that 'info' command and promptly ran the one emacs command I have memorized: C-x C-c :)
the best part is when a man page has an entry like this, and then the info page is a copy of the man page...
Re: Things People Hate about Your Open Source Docs
#29>Lack of realistic examples
So true.
I've frequently had the impression that writers are plain missing the point - with the most dense, clever self-satisfying examples as opposed to verbose, simple and instructive.
Re: Things People Hate about Your Open Source Docs
#30Earlier quoted context omitted.
This is 100% true. I am constantly frustrated by incomplete code examples in documentation. The one thing in particular that bothers me the most are when Python snippets don't show the import statements. do_magic(param, other_param) Where do I import do_magic from?!?!
Same thing in Java -- if there's a class named something commonplace like "Transaction" or "Connection", it's going to be pretty critical to understand whose implementation that refers to.
Same in .Net, although Resharper (http://www.jetbrains.com/resharper/) has made my life a lot easier by giving me much better import/using suggestions, although not 100% foolproof.