How I Judge the Quality of Documentation
ericholscher.com
How I Judge the Quality of Documentation
1–10 of 75 posts
Re: How I Judge the Quality of Documentation
#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.
Re: How I Judge the Quality of Documentation
#3Speaking 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
Re: How I Judge the Quality of Documentation
#4> 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.
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?
Re: How I Judge the Quality of Documentation
#5Speaking 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
Most languages now have a tool for writing and hosting documentation to make this as easy as possible for you. The author of the post runs http://readthedocs.org/, which is primarily used by Python developers, for instance.
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.
Re: How I Judge the Quality of Documentation
#6> 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.
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 it be better for someone to share a link (potentially in a different language) and the recipient sees it in their own language?
That said, language prefixes should still exist, for debugging if nothing else.
Re: How I Judge the Quality of Documentation
#7> 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.
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.
Re: How I Judge the Quality of Documentation
#8Earlier 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.
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 dig through the site to get back the text the comment author was talking about.
Re: How I Judge the Quality of Documentation
#9Speaking 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
Most languages now have a tool for writing and hosting documentation to make this as easy as possible for you. The author of the post runs http://readthedocs.org/ , which is primarily used by Python developers, for instance. 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 pa…
However, Sphinx & Read the Docs is not just for Python :)
http://ericholscher.com/blog/2014/feb/11/sphinx-isnt-just-fo...
Re: How I Judge the Quality of Documentation
#10Next 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 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.