[deleted]
How I Judge the Quality of Documentation
21–30 of 75 posts
Re: How I Judge the Quality of Documentation
#22"If your documentation is a directory full of files on GitHub, I close the tab."
Without even stopping to see if there is an INDEX or README that gives the files a hierarchy? Without considering whether those files are well-written? Without remembering that plain text files are portable, easy to author in many tools, and easy to view on many devices? You'd rather see a glitzy website with no content?
"If your documentation is generated from source code, I am immediately skeptical."
Even though keeping documentation with the code it documents makes it more likely the two will be in sync? Even though some library authors use their source code documentation tool to write entire files that are nothing but documentation? Maybe you're viewing it wrong: my documentation is not generated from source code. My documentation includes the source code and will generate the library.
Since he seems bent on judging things in 30 seconds I guess it is inevitable that he will elevate form over substance.
Re: How I Judge the Quality of Documentation
#23ReadTheDocs [1] is by far the best platform to have documentation. The simple reason: Everything gets into an Elasticsearch server (sponsored by Rackspace) which means you get wonderful full text search (and faceting).
See:
http://read-the-docs.readthedocs.org/en/latest/search.html?q...
Re: How I Judge the Quality of Documentation
#24"If your documentation is a directory full of files on GitHub, I close the tab." Without even stopping to see if there is an INDEX or README that gives the files a hierarchy? Without considering whether those files are well-written? Without remembering that plain text files are portable, easy to author in many tools, and easy to view on many devices? You'd rather see a glitzy website with no content? "If your documen…
Sure, keep the files as plain text in the repo, I'm all for that. Just don't make it the main interface for viewing them. You are really arguing that a GitHub file browser is the best UX for viewing documentation?
Sure, keep documentation about code in the source code. Where exactly in the source code does your tutorial go?
You seem to be reading into a lot of things that aren't in the article based on what you want to hear.
Re: How I Judge the Quality of Documentation
#25Next time you come across a project documented solely in Lithuanian / Japanese / Swahili, I hope you will refer to http://ericholscher.com/blog/2014/feb/27/how-i-judge-documen... for insight. English is the de-facto language of the Internet (let's not discuss here how damaging that is to English as a language in general). I strongly believe that public-facing software projects should be documented in English first an…
I'm a consultant in Quebec and I've seen too many companies document code in French. Sometimes variable and function names are in a mix of French and English. The worse is when your errors and exceptions are in French: you get very confused international clients. English reading and writing skills are a MUST for programmers and I envy your working in what sounds like a much nicer code base.
Absolutely! Codebases in "franglais" are terrible. Also, when documenting such codebases, I cringe whenever I see public APIs with mixed language members.
Re: How I Judge the Quality of Documentation
#26Next time you come across a project documented solely in Lithuanian / Japanese / Swahili, I hope you will refer to http://ericholscher.com/blog/2014/feb/27/how-i-judge-documen... for insight. English is the de-facto language of the Internet (let's not discuss here how damaging that is to English as a language in general). I strongly believe that public-facing software projects should be documented in English first an…
Specifying the language with an /en/ in the URL isn't a major inconvenience, and allows for future expansion at the cost of 3 additional characters in an URL. Including it says "I planned ahead and worked intentionally", which shows you care, which fundamentally is what this article is driving at. And yes, documentation should generally be in English first - it's the current language of science and tech, just as it w…
Adding an /en/ when you decide to translate the documentation isn't a major inconvenience either. I would rather add it when it's relevant than include something that will probably never be anything but noise. This is pretty much the same reason I don't put in a bunch of non-functioning UI controls that will hopefully have features attached in the future — my interface is meant to be practical, not aspirational.
Re: How I Judge the Quality of Documentation
#27"If your documentation is a directory full of files on GitHub, I close the tab." Without even stopping to see if there is an INDEX or README that gives the files a hierarchy? Without considering whether those files are well-written? Without remembering that plain text files are portable, easy to author in many tools, and easy to view on many devices? You'd rather see a glitzy website with no content? "If your documen…
Form follows function, to be sure, but form also follows function. That is, if you don't have function, one way to tell is a lack of form.
It's not always true, but it's an indication of a lack of function, improper form.
Re: How I Judge the Quality of Documentation
#28I'm glad that we do everyone one of these, except for language.
On the versioning we go one step further. Not only is the documentation available at every version, such as:
http://www.gojs.net/1.3.3/api/symbols/Diagram.html
The latest version is also available at its own eternally up-to-date permalink (also the default), so if you want to bookmark the documentation, or samples, or intro guide at whatever the latest version might be, you can just substitute latest for the version number:
http://www.gojs.net/latest/api/symbols/Diagram.html
(The same goes for the current Beta, if there is one, at /beta/)
In addition, the top of the page in the documentation (or bottom of the page, in the samples) always displays the currently-viewed version number.
We try hard to make sure nearly all classes are introduced in prose, and have a separate set of technical introduction pages to accompany with several live examples (One of the more wonderful things about writing a JavaScript library!)
Re: How I Judge the Quality of Documentation
#29I think the author is conflating "quality" of documentation with "usability" of documentation. They are probably correlated, and this might make a good filter for ignoring BAD documentation, but a documentation site can be very "usable" without containing quality content, and it can contain quality content without being "usable"
Re: How I Judge the Quality of Documentation
#30"If your documentation is a directory full of files on GitHub, I close the tab." Without even stopping to see if there is an INDEX or README that gives the files a hierarchy? Without considering whether those files are well-written? Without remembering that plain text files are portable, easy to author in many tools, and easy to view on many devices? You'd rather see a glitzy website with no content? "If your documen…
Sure, keep the files as plain text in the repo, I'm all for that. Just don't make it the main interface for viewing them. You are really arguing that a GitHub file browser is the best UX for viewing documentation? Sure, keep documentation about code in the source code. Where exactly in the source code does your tutorial go? You seem to be reading into a lot of things that aren't in the article based on what you want…
less(1)
vi(1)
emacs(1)
firefox(1)
google-chrome(1)
Microsoft Word or Internet Explorer, if that's your thing!
As for "where does your tutorial go," see for example "Control.Pipes.Tutorial".
http://hackage.haskell.org/package/pipes-4.0.0/docs/Pipes-Tu...
If someone can't figure these things out, by all means, go use someone else's library. This sort of documentation would not be acceptable for a consumer product like TurboTax, but a programmer needs to know how to view a text file.