Live data from Hacker News

How I Judge the Quality of Documentation

ericholscher.com

31–40 of 75 posts

Re: How I Judge the Quality of Documentation

#31

"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.

To me it's more common that elaborate form covers up lack of function.

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.

Re: How I Judge the Quality of Documentation

#32
I 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.

Re: How I Judge the Quality of Documentation

#33
> 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?

Re: How I Judge the Quality of Documentation

#34

Next 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 have to say that I completely disagree with this perspective. Yes, currently our 'lingua franca' of business and technology is English, but I feel that is a problem, not a solution.

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.

Re: How I Judge the Quality of Documentation

#35
Historically, 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.

Re: How I Judge the Quality of Documentation

#37
It'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.

Re: How I Judge the Quality of Documentation

#38

Historically, 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 pl…

From 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.

Re: How I Judge the Quality of Documentation

#40
I 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?

Post reply on HN