How I Judge the Quality of Documentation
ericholscher.com
ericholscher.com
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.
Not only is this good if you ever want to share the code, but I find myself thinking about programming in English.
I think that is what you are advocating in part of your response.
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 was when French, German, Latin, Arabic, and Greek proceeded it.
It's a problem because it unfairly advantages native English speaking people in business. It creates a barrier of entry to people who did not learn English from an early age, along with their native language. It makes it much harder for those people to be part of business, technology, and open source. It degrades the quality of communication and work-output by forcing non-native speakers to express themselves in English.
Does being a good engineer imply being good at spoken natural languages? I have met some brilliant engineers in China who are barely functional in English. If you were to interact with them purely in English, you would think you're talking to a 5 year old, based on the language alone. Some of the engineers I've met in China aren't even that capable with English, but are wonderful developers writing interesting things.
Sometimes they created documentation in Chinese, sometimes in English. Guess which one they were able to express their ideas in more clearly? Chinese.
When you write, you should write in your native language, and express your idea to the best of your ability. Then, if you want to translate that to other languages later, to make it more accessible to others, do that as a separate task. Maybe hire a professional technical translator to do that work.
You gave this example of coming across a page written in Lithuanian or Japanese, presuming of course that you're not a native speaker of those languages. Fine, that's exactly how every Chinese native speaker feels when they come across a page of English text, every day of their life as a developer... but they figure it out, even with terrible language skills. You know why? Not because "English is the language of business" but because they just want to learn about the content, and aren't going to try to force you to write it in Chinese so they can do that. If all those pages were in French they would figure that out too.
With the attitude you expressed above, the main people who benefit from this are native English speakers. Anyone else is still in the 2nd language boat. So then of that group, you advantage people with a talent for natural languages, or who are wealthy enough, as a child, to have access to education resources to learn another language. As a former English teacher in China, I promise you that this is a huge economic divide. The kids who can afford to learn English succeed, those who can't, don't. That's fucked up, and not at all a reasonable way to approach business. A good engineer should not be left with no opportunities because they grew up poor, or have no real talent learning foreign languages.
In business, such concerns about equality and fair access might not be very important, because unfair advantages and competition are what much of business is all about... but in open source, and in modern businesses that are learning from the open source model, I think being concerned with inclusiveness is paramount. So yes, you might have to struggle through reading something like this:
https://github.com/be5invis/youki/blob/master/README.yk
... but it doesn't take much to punch "Youki 是一个文档生成语言，其具备完整的编程特性和完备的宏特性，使之可作任意复杂的文章。Youki 是完全开放源码的，依照 MIT 协议发布。" into Google Translate (or use the auto-translate features of Chrome). Now we can all get on with our lives and use be5invis's cool documentation generation tool.
Would you prefer to exclude him and his work from our community by forcing him, a Chinese square-peg through some English speaking round-hole? Personally, I'm willing to do a little extra work to understand him in his own language. I also appreciate deeply that he has to do that work constantly, in order to read my code/docs in my native language.
A common documentation language functions as a technical standard, like IPv4. Sure, you can use your own standard, perhaps IPX, but you'll only be able to communicate with a much smaller group of people.
It's hard to get documentation written in the first place, let alone good documentation. Making it 'fair' by saying that documentation has to be effectively splintered into every native language is a sisyphean task.
As always, write to your audience. If it's a general tech audience, that means English. If it's Chinese engineers who don't speak English well, that means Chinese. But those Chinese engineers are going to have an easier time interpreting foreign documentation if it's all in one language rather than 50.
Wouldn't it be nice if we all spoke the same language?
So much less conflict, so much more efficient.
Wouldn't it be nice if we all had the same cultural background?
So much less conflict, so much more efficient.
Wouldn't it be nice if we all looked and acted exactly the same?
So much less conflict, so much more efficient.
Wouldn't the world be a nicer place without all this pesky diversity?
So much less conflict, so much more efficient.
In the end, there's not one correct answer. The point of documentation is communication. Communication is a very malleable thing. It is negotiated on demand and the form of it varies a lot. The real beauty of many of our underlying systems is their ability to negotiate a protocol, not the pervasive standard use of a single protocol.
A couple personal stories:
Once, I was in Switzerland, and went to a Chinese restaurant. The waitress spoken Cantonese (1st), Swiss (2nd), and Mandarin (2nd). I spoke English (1st), German (2nd), and Mandarin (2nd). We quickly figured out that we could communicate most effectively in Mandarin, and so we did.
Later on in that trip, I went to an Italian restaurant. The owner spoke Italian and some very limited Swiss, but no English. I couldn't speak Italian or Swiss enough to communicate with him. Instead, we used gestures, body language, and pictures. It worked out, and I got one of the best plates of lasagna I've ever had.
The message here is that language is not standardized, and will never be, so calling English a standard is just a failure of reason. It's a sub-par medium for communication for the majority of the world.
You never know who is going to walk in the door of your restaurant to order food. Do your best to communicate with them, without too many assumptions, and you'll find that communication can be negotiated easily.
That said, in more practical terms, I actually encourage the use of less text, but more pictures, examples, and tactile learning approaches in documentation. When text is required, it should be "High Fidelity" and that means, written in the native language of the person writing it. Then, you have the ability to degrade fidelity later, by translating it to whatever language you've negotiated for when the native language doesn't match.
I see English in programming as the somewhat lowest common denominator. At least in the "western world".
From all the 4 languages I learned and some more I messed around with, English was the easiest to get to a basic level. On Par with Spanish. This is highly biased of course.
Although my mother tongue is German(Swiss), I usually avoid documentations, tutorials, etc in German for multiple reasons.
- The mix of english terminology, germanized terminology and normal German makes it hard to read.
- They are mostly just translated and not rewritten, which sometimes leads to some strange formulations.
- I'm forgiving/ignorant for grammatical errors in foreign languages
- They tend to be outdated.
I agree that documentation should only use as few text as possible and as much necessary. Editable and runnable examples are the best way in my opinion. Also, no matter what language, documentation should be written using simple words, short sentences and not try to win a pulitzer prize.
I don't mind documentation in English. What really pisses me off is, when I have to work with software where the developers/designers clearly didn't account for things like letters with stuff on it (éàüöøñ…), variable sentence lengths, date formats, etc.
However it's currently the best universal medium we have, and you're arguing to actively remove that, rather than replace it with a system that improves global communication.
Not to mention "can I have one of these items of food that you prepared" is a much easier concept to convey than technical information, which can get quite nuanced. Figuring out how to analyse a stack trace is not something you can do with body language. And body language isn't universal, either.
Yes, language is not standardised, but we're talking about language for a specific purpose here, not language in general. Don't get me wrong. I like to be around a variety of languages, though I'm a monoglot. But I don't see the point in trying to remove an extant common language out of a philosophical sense of fairness, when it would actually decrease communication between people.
Wouldn't the world be a nicer place without all this pesky diversity?
The slippery slope you're painting here doesn't exist. Having a common language is not the same as turning everyone into WASPs and doesn't lead to it, any more than speaking Spanish means that Mexicans, Peruvians, and Spaniards are the same culturally. Or speaking French meaning that the French, Algerians (half of...), and Quebecois are the same culturally.
English is currently the best language for software and computer engineering.
So, no, sorry, learn English. Once upon a time to do physics and chemistry you needed German--so, it could be worse.
(And if you didn't win the lottery and start with that language: that sucks, but you'll be that much more valuable if you can act at a translator.)
I have never come across a situation such as you described and I am very curious to see proof positive of someone phenomenally bad at English and phenomenally great at programming. Please, help expand my horizon!
For the record, I am a non-native English speaker.
System that only make sense in a specific context should be OK to be documented in the most appropriate language.
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.
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.
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.
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.
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.
What's better, the docs for Backbone.Marionette[0], or Backbone[1]?
[0]: https://github.com/marionettejs/backbone.marionette/tree/mas... [1]: http://backbonejs.org/
Offline or online viewing? Should I need a web connection to read the documentation?
It's not always true, but it's an indication of a lack of function, improper form.
What's important is writing an understandable library. Documentation cannot paper over a bad design. If it takes a ream of documentation to document something, sometimes the time spent on the docs would have been better spent writing a cleaner interface.
And simple documentation is in proper form. I'd rather spend time writing documentation than learning some new gee-whiz framework for writing documentation. Even time spent putting together a website is time that could have been spent writing documentation.
Another advantage of in-tree documentation is that the docs come with the code. When there's a separate website, you have to consult this separate place. Someone else in this thread pointed out that sometimes you can't get docs for an old version. Not a problem when the docs are in the VCS along with the rest of the code.
> 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?
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.
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!)
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
For Go, the standard toolchain is the builtin go doc tool (http://godoc.org/code.google.com/p/go.tools/cmd/godoc), and the GoDoc website for hosting (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.
http://ericholscher.com/blog/2014/feb/11/sphinx-isnt-just-fo...
https://sourcegraph.com/github.com/sergiotapia/smitego
For Go, godoc.org is also great.
RIP Accept-Language.
That said, language prefixes should still exist, for debugging if nothing else.
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.
It is nice to try and help a user, but you should always let them override your language decision.
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.
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.
Screenshot: http://i.imgur.com/qUWjWzb.png
[1] `'goudy old style','minion pro','bell mt'` etc
Tests.
I closed the tab after reading this.
Donald Knuth would disagree.
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/
Judge documentation by its quality of content, not its publishing platform.
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).
(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.)
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?
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.
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.
Here's a couple of examples: http://distri.github.io/pixie-canvas/docs/ http://www.danielx.net/interactive/docs/ <- The meta one
See:
http://read-the-docs.readthedocs.org/en/latest/search.html?q...
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
example.com/how-to-bar-the-foo-v1
docs.example.com/en/1.0/foo#bar
Is it on a wiki? Leave project and never come back.