Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How I Judge the Quality of Documentation

ericholscher.com

Post reply on HN
Print view View original

61–70 of 75 posts

Re: How I Judge the Quality of Documentation

#61

Post by chacham15 »

First 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/

Re: How I Judge the Quality of Documentation

#62

Post by thoward37 »

vacri wrote: post #50
thoward37 wrote: post #34

Earlier quoted context omitted.

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…

Most people in the world do not speak one of the uber-languages (english, chinese, spanish etc). These people are particularly poorly served by a drive to document in their native language rather than a common language. If someone only speaks Xhosa and never gets to exercise a documentation-common-language, then they'll only be able to read and contribute to documentation in Xhosa, which is a much smaller community t…

I don't disagree. The problem of standards is that sometimes they help and sometimes they hurt. They always seem like a great solution, but rarely are.

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.

Re: How I Judge the Quality of Documentation

#63

Post by sqs »

sergiotapia wrote: post #3

Speaking 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 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

I 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

For Go, godoc.org is also great.

Re: How I Judge the Quality of Documentation

#64

Post by pseut »

lowboy wrote: post #59
massysett wrote: post #30

Earlier quoted context omitted.

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…

I know how to view a text file, or even navigate a directory of them. But as forsaken said, a GitHub file browser is often not the best UI for viewing documentation, especially when you're already in a browser. 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/

> What's better, the docs for Backbone.Marionette, or Backbone?

Offline or online viewing? Should I need a web connection to read the documentation?

Re: How I Judge the Quality of Documentation

#65

Post by smoe »

thoward37 wrote: post #62
vacri wrote: post #50

Earlier quoted context omitted.

Most people in the world do not speak one of the uber-languages (english, chinese, spanish etc). These people are particularly poorly served by a drive to document in their native language rather than a common language. If someone only speaks Xhosa and never gets to exercise a documentation-common-language, then they'll only be able to read and contribute to documentation in Xhosa, which is a much smaller community t…

I don't disagree. The problem of standards is that sometimes they help and sometimes they hurt. They always seem like a great solution, but rarely are. 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…

I agree that language is not standardized and should never be.

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.

Re: How I Judge the Quality of Documentation

#66

Post by Gigablah »

dominicrodger wrote: post #53
suprjami wrote: post #51

Not 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 publ…

> 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. / /docs" rel="nofollow">https://github.com/ / /docs ).

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

Re: How I Judge the Quality of Documentation

#67

Post by vacri »

thoward37 wrote: post #62
vacri wrote: post #50

Earlier quoted context omitted.

Most people in the world do not speak one of the uber-languages (english, chinese, spanish etc). These people are particularly poorly served by a drive to document in their native language rather than a common language. If someone only speaks Xhosa and never gets to exercise a documentation-common-language, then they'll only be able to read and contribute to documentation in Xhosa, which is a much smaller community t…

I don't disagree. The problem of standards is that sometimes they help and sometimes they hurt. They always seem like a great solution, but rarely are. 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…

It's a sub-par medium for communication for the majority of the world.

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.

Re: How I Judge the Quality of Documentation

#68

Post by shiven »

thoward37 wrote: post #34
btbuildem wrote: post #10

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…

Ok. Now I am genuinely curious. Could you point me to projects/code samples from this person?

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.

Re: How I Judge the Quality of Documentation

#69

Post by Yahivin »

I 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://www.danielx.net/interactive/docs/ <- The meta one

Re: How I Judge the Quality of Documentation

#70

Post by pseut »

zdw wrote: post #19
btbuildem wrote: post #10

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…

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 /en/ to the URL creates an expectation that there are translations in other languages.
Post reply on HN