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

11–20 of 75 posts

Re: How I Judge the Quality of Documentation

#11

Post by bajsejohannes »

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…

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

Re: How I Judge the Quality of Documentation

#12

Post by gnud »

ramchip wrote: post #8
couchand wrote: post #7

Earlier quoted context omitted.

Wouldn'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.

If 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 d…

If sites actually respected accept-language, I think this UI problem would be fixed by browsers in short order (change accept-language and reload)

Re: How I Judge the Quality of Documentation

#13

Post by BarkMore »

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

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

Re: How I Judge the Quality of Documentation

#14

Post by muyuu »

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…

That depends on the potential audience of the docs I guess.

Re: How I Judge the Quality of Documentation

#17

Post by forsaken »

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…

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

Re: How I Judge the Quality of Documentation

#18

Post by green7ea »

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

Re: How I Judge the Quality of Documentation

#19

Post by zdw »

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 was when French, German, Latin, Arabic, and Greek proceeded it.

Re: How I Judge the Quality of Documentation

#20

Post by antsar »

adammil wrote: post #15

I'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.

Perhaps, 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.
Post reply on HN