10 ms·
How I Judge the Quality of Documentation
- mooism2 13y ago> If you don’t provide a language in your URL, you are implicitly sending the message that the documentation will never be translated. RIP Accept-Language.
- forsaken 13y agoA good host will redirect to the proper version of the docs when presented with a root URL, but how do you link someone to a specific language, if the Accept-Language is the canonical source for this information?
- RossM 13y agoWouldn't it be better for someone to share a link (potentially in a different language) and the recipient sees it in their own language? That said, language prefixes should still exist, for debugging if nothing else.
- couchand 13y agoWouldn't the use case be just "link to the right spot in the docs" and the user's client requests the appropriate language automagically? That way the link is valid for everyone, and it shows each their preferred language.
- ramchip 13y agoIf I'm reading something in language A which deep links me to some documentation, I think it's quite likely that I want to see it in language A, not language B which happens to be my machine's native language. For example recently I was linked to a Microsoft page via a comment, but it rendered in Japanese, which was a pain to me because I was looking for a specific citation in English. I had to switch language then dig through the site to get back the text the comment author was talking about.
- gnud 13y agoIf sites actually respected accept-language, I think this UI problem would be fixed by browsers in short order (change accept-language and reload)
- jacalata 13y agoNo. I read multiple languages. Maybe my friend wants me to explain something in the docs they are reading - should I need to change my browser language to check it for him? I want to look something up from a university computer where I am studying in France - I can never see the docs in my native language from a public computer? I want to look something up on my friends laptop - it has to be in his preferred language? It is nice to try and help a user, but you should always let them override your language decision.
- cobralibre 13y agoAutomatically selecting a language based on the Accept-Language header value can be a nice feature but isn't a universal solution, and there are reasons to not do it. As another commented noted, it can be helpful to have the desired language specified via the URL for bookmarking and permalink reasons. Another problem is that some users don't know how to configure their browsers to declare a preferred language. Another problem is that some users do not have a single preferred language, and may prefer one language for certain contexts and another language for others. For such users, it's preferable to simply pick the language that they want from the site's UI. Some sites automatically choose a language based on the client's location, and for similar reasons, this can be more annoying than helpful to certain users.
- sergiotapia 13y agoSpeaking of documentation... I'm starting work on my first Go library and I want to make sure I'm not fighting against the ecosystem. https://github.com/sergiotapia/smitego https://github.com/sergiotapia/smitego How do go programmers write their documentation? Do I just write comments on func's and use a tool to generate it? What the standard? Thanks
- Lukasa 13y agoMost languages now have a tool for writing and hosting documentation to make this as easy as possible for you. The author of the post runs http://readthedocs.org/ http://readthedocs.org/, which is primarily used by Python developers, for instance. For Go, the standard toolchain is the builtin go doc tool (http://godoc.org/code.google.com/p/go.tools/cmd/godoc http://godoc.org/code.google.com/p/go.tools/cmd/godoc), and the GoDoc website for hosting (https://godoc.org/-/about https://godoc.org/-/about). Using that pair of tools will be a good start. The advantage of these standardised tools is that it gives most documentation for projects in a given language a common 'look'. Go libraries have one kind of appearance, Python ones another, and so on. This tends to make navigating around much easier.
- forsaken 13y agoHowever, Sphinx & Read the Docs is not just for Python :) http://ericholscher.com/blog/2014/feb/11/sphinx-isnt-just-for-python/ http://ericholscher.com/blog/2014/feb/11/sphinx-isnt-just-fo...
- BarkMore 13y agoSee http://blog.golang.org/godoc-documenting-go-code http://blog.golang.org/godoc-documenting-go-code for Go documentation guidelines. Use the godoc tool included with the Go distribution to read package documentation locally. Use godoc.org to view documentation on the web. The documentation for your package is at http://godoc.org/github.com/sergiotapia/smitego http://godoc.org/github.com/sergiotapia/smitego .
- sqs 13y agoI created a website that automatically generates documentation and examples for libraries in Go (and Python, Ruby, and JavaScript). Here's your project on it: https://sourcegraph.com/github.com/sergiotapia/smitego https://sourcegraph.com/github.com/sergiotapia/smitego For Go, godoc.org is also great.
- btbuildem 13y agoNext 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-documentation-quality/#language 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 and foremost, with translations to other languages added as resources allow. I work for a small company in Quebec (that's the Canadian province that has a Language Police) - despite most of the team being Francophone, all our internal documentation and code docs are in English. Why would that be? Because everyone realizes, without ever really having discussed it, that it is the only efficient way to do it, if we want to collaborate with others, if we want to grow, if we want others to contribute, having everything in French would be creating unnecessary hurdles.
- bajsejohannes 13y agoSpot on! English is not my first language, but I still document and use English variable names in all my code. This includes the tinyest one-off scripts. Not only is this good if you ever want to share the code, but I find myself thinking about programming in English.
- muyuu 13y agoThat depends on the potential audience of the docs I guess.
- forsaken 13y agoThe article isn't saying to write things in another language as canonical, it's just saying put the language in the URL so later you can add other languages without breaking the URL. I think that is what you are advocating in part of your response.
- green7ea 13y agoI'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.
- adammil 13y agoI'm with the author until he says to encode extra information into the URL. If the docs and the site are built well, you should find everything you need while completely ignoring the URL structure.
- antsar 13y agoPerhaps, but a well-designed URL structure is helpful when one sees a deep link to the site and wants to know what they'll find. example.com/how-to-bar-the-foo-v1 docs.example.com/en/1.0/foo#bar The latter form clearly presents the possibility of jumping straight to a different version's foo docs, to the docs homepage, etc. I'd consider this a quality of good UX.
- justinj 13y ago> When you look at a project’s code for the first time, what are the things you look for? Tests.
- clarry 13y agoObvious bugs.
- deleted 13y ago[deleted]
- massysett 13y ago"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.
- forsaken 13y agoSure, 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.
- massysett 13y agoless(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-Tutorial.html 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.
- lowboy 13y ago
- susi22 13y agoReadTheDocs [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=great http://read-the-docs.readthedocs.org/en/latest/search.html?q... [1] https://readthedocs.org/ https://readthedocs.org/
- rogerbinns 13y agoSadly they aren't useful if your documentation is more complex. For my project I do use Sphinx for the doc, but there is a prebuild stage where some of the API information is extracted from non-Python text files (C source). Another part runs the example code and captures it as RST. There are various other nuances like that. readthedocs can't build that (make docs would work on my tree). I've contacted them several times to ask for how to proceed and never get an answer. You can see my Sphinx doc not at readthedocs but at http://rogerbinns.github.io/apsw http://rogerbinns.github.io/apsw
- simonsarris 13y agoI'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 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 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!)
- ben336 13y agoI 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"
- schmichael 13y agoI really hope the golang community doesn't consider godoc.org to be the beginning and end of their project documentation. It's a fantastic service and probably Good Enough for small projects, but if larger projects don't include prose like Effective Go it's going to really hurt adoption.
- burntsushi 13y agoThere is plenty of room for prose generated by godoc in a package's documentation. (Which precedes the `package ...` line in a source file.)
- technomancy 13y ago> If your documentation is a directory full of files on GitHub, I close the tab. I don't get this at all. Why is a static site (where it's unclear which branch it was generated from or when) better than a bunch of nicely-rendered markdown files stored in a directory?
- MrZongle2 13y agoNo kidding. I'll take a Markdown or plain-text README over a slick set of web pages if the former is current and thorough. Heck, I'd settle for either of those.
- incision 13y agoHistorically, I've been accessing documentation as an administrator rather than a programmer. There are a couple of documentation habits that have driven me half mad over the years. * Broken Usage Examples: It's bad enough when an example demonstrating some now deprecated feature hangs around in the introductory text that every new user will cut their teeth on. It's an immediate vote of no confidence when typos or plainly busted syntax makes it into the docs. * Confusingly Abstract Examples: Please no ./foobar -f foo -b bar -i foobar.foo -o barfoo.bar. Just paste an actual usage example, explain it and be done with it. A cousin to this is the use of overly complex "Look how clever I am!" examples. * Explanation By Analogy / Google: Saying things like "configuration files use ____ syntax" without summarizing or at the very least linking to a definitive reference for "____ syntax". * Insane Defaults: This is really a design concern, but if we're already past that point and destructive / poor performing default behavior is the chosen path at least clearly document that fact. --- On a related note, when I'd just started to augment my sysadmin background with code I saved time by writing scripts, small utilities and general automation. As I've learned more, my savings increasingly come from being able to jump into the code to diagnose the odd behavior of poorly documented programs instead of endless profiling, searching and experimentation.
- noobface 13y agoFrom a systems engineering perspective: Any marketing, at all, in documentation really complicates my research. I was already interested in the product, and I'm trying to solve a problem with it. I understand the use case. I don't need to know how this saved X company $XXX,XXX dollars per second over the past billion years. Obscuring the meat-and-potatoes technical specifications behind phrases like, "cloud ready" and "virtualization optimized" just makes it harder to evaluate the product.
- dlitz 13y ago> If your documentation is a directory full of files on GitHub, I close the tab. I closed the tab after reading this.
- rok3 13y agoSeriously, not every project warrants a full-blown site / custom web interface for the documentation.
- vacri 13y agoIt's hard to take documentation advice from a blog with a low-contrast text. If I have to struggle a little to read your text, it's clear you're more interested in looking cool than conveying information - a sin as bad as any in the article's list. Not everyone speaks English? Yes, well, not everyone has an excellent screen that brings out the colours you've selected just so.
- usea 13y agoNot to mention whatever web font that is [1] renders terribly in windows. If I cannot read your article on criticizing text communication without copying and pasting the contents into a text editor, I close the tab. Screenshot: http://i.imgur.com/qUWjWzb.png http://i.imgur.com/qUWjWzb.png [1] `'goudy old style','minion pro','bell mt'` etc
- Moru 13y agoYes I had the same problem but at the end I found a useful button called "Page source". That one makes the page readable again. It's just a normal textfile then .-)
- chrisBob 13y agoPlease don't make me open an MS Word file to read your documentation.
- oskarth 13y agoI agree with most of these, but this one stuck out. > I believe that translating documentation is a really important step towards helping people learn to program. Someone shouldn’t have to learn Programming and English at the same time. Really? Knowing English is pretty much a prerequisite for programming. Should all UNIX man pages exist in other languages too? That said, of course tutorials in other languages are useful, but it's hardly the job of the open source project. EDIT: "Prerequisite for programming" in the literal sense is obviously wrong. It's very useful though, and pretty much a must to participate in most big open source projects (mailing lists, issue trackers, comments, documentation). Is this really a controversial statement?
- avmich 13y ago> Knowing English is pretty much a prerequisite for programming. Emphatically no. You can be a brilliant programmer without knowing English. Of course, that doesn't say that knowing English somehow hurts. I've met many programmers smart enough to learn programming to expert levels despite not knowing English and having to rely on whatever was available in other languages - sometimes that was plenty, sometimes they had to reinvent algorithms. At the same time I know other good programmers who were faced with the problem of learning programming and English at the same time and succeeded at that.
- jj00 13y agoI've been evaluating using a wiki for some of our documentation, with DokuWiki. It uses plain-text markup files, but also allows for some collaboration between users. I can see where it wouldn't be so hot on the version front, but I'm hoping that we can come up with a procedure to keep those text files in a repository.
- conductr 13y agoI use most code from OS projects and I've always preferred good use examples. I see a lot of overly simple use examples which really give no direction for a new user(Apple ios examples). Any format works but list all the methods of a class. And list what arguments they accept and the acceptable types of each. And finally list what is returned. I document my code as a business logic statement. Eg given credit card, process payment. I then write the validations in a way that reads simple and thus is documentation. If it's a complex line that takes more that a few seconds to parse mentally. I will write out what it does. That's pretty rare. Non programmers never see my code so that works just fine.
- duwease 13y agoI would have rules for how I judge documentation, but I see it so rarely that "any documentation at all" is the highest honorific.
- mystral 13y ago"If you included all of the things needed to document a project in source, your code would be unreadable." Donald Knuth would disagree.
- feralmoan 13y agoWorth it for the hint on MkDocs alone - thanks Eric Holscher!
- suprjami 13y agoNot reading Github pages is stupid and ignorant. You can use Github as a publishing platform. It CAN be good enough for documentation for a small or medium sized project. This can allow quick creation of fairly nice docs, allowing the coder to get back to coding. Hell, all the kernel docs are text files. You gonna tell me you'll never read them on principle? Judge documentation by its quality of content, not its publishing platform.
- dominicrodger 13y ago> If your documentation is a directory full of files on GitHub, I close the tab. With GitHub Pages, Read the Docs, and other places to host generated documentation for free, not making an effort is unforgivable. He's not arguing against GitHub pages - he's arguing against just linking to a file/folder in your GitHub repository and thinking you're done (e.g. https://github.com/<org>/<project>/docs https://github.com/<org>/<project>/docs).
- Gigablah 13y agoGitHub renders markdown files. So the difference between clicking on navigation links in a documentation website and clicking on markdown files in a GitHub docs folder is... the CSS theme.
- cobralibre 13y agoAs I see it, the author of TFA is simply offering some heuristics for judging whether or not he's going to have a hard or an easy time working with a project's documentation. So in this view, presenting documentation using a structure that is specifically intended for documentation is taken as an indicator of care and attention to detail. I wouldn't say that he's arguing that a directory full of files isn't functionally equivalent or isn't useful. (Personally, out here in the real world, I'll put up with all sorts of limitations — even a complete lack of documentation — if somebody else's existing code solves a problem that I have.)
- coldtea 13y agoHow I judge the quality of documentation: Is it on a wiki? Leave project and never come back.
- chacham15 13y agoFirst of all, to begin with a famous quote: Documentation "…when it is good, it is very, very good; and when it is bad, it is better than nothing." - Dick Brandon Second of all, I couldnt disagree more with this statement for certain types of projects: "If you included all of the things needed to document a project in source, your code would be unreadable." I believe in self documenting code with additional information for API functions. A really good way of doing this is with wonderful tools like Doxygen: http://www.stack.nl/~dimitri/doxygen/ http://www.stack.nl/~dimitri/doxygen/
- Yahivin 13y agoI judge the quality of documentation by having interactive examples. Words are great, and also important, but interactive demos that exist within the documentation go a long way to assisting people in learning your project. Here's a couple of examples: http://distri.github.io/pixie-canvas/docs/ http://distri.github.io/pixie-canvas/docs/ http://www.danielx.net/interactive/docs/ http://www.danielx.net/interactive/docs/ <- The meta one