How I Judge the Quality of Documentation • Hacker News Board

Re: How I Judge the Quality of Documentation

#71

Post by burntsushi » Fri, Feb 28, 2014, 3:36 AM UTC

schmichael wrote: post #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.

There is plenty of room for prose generated by godoc in a package's documentation. (Which precedes the `package ...` line in a source file.)

Re: How I Judge the Quality of Documentation

#72

Post by jacalata » Fri, Feb 28, 2014, 3:58 AM UTC

couchand wrote: post #7

forsaken wrote: post #4

Earlier quoted context omitted.

A 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?

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.

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

Re: How I Judge the Quality of Documentation

#73

Post by hrktb » Fri, Feb 28, 2014, 11:43 AM UTC

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 used to think the same. But as for any rule, there are exceptions. Documenting a Swahili project dealing with parsing official Swahili resources may not be best done in english, just translating every idiomatic notion into english would be a waste of time, effort and won't help anyone.

System that only make sense in a specific context should be OK to be documented in the most appropriate language.

Re: How I Judge the Quality of Documentation

#74

Post by cobralibre » Fri, Feb 28, 2014, 7:06 PM UTC

mooism2 wrote: post #2

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

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

Re: How I Judge the Quality of Documentation

#75

Post by cobralibre » Fri, Feb 28, 2014, 7:19 PM UTC

Gigablah wrote: post #66

dominicrodger wrote: post #53

Earlier quoted context omitted.

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

As 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.)