How I Judge the Quality of Documentation

Re:How I Judge the Quality of Documentation by zdw on Thursday February 27, 2014 @12:29PM (#7313476)

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.

[ Parent | on HN ]

Re:How I Judge the Quality of Documentation by chc on Thursday February 27, 2014 @01:33PM (#7313968)

Adding an /en/ when you decide to translate the documentation isn't a major inconvenience either. I would rather add it when it's relevant than include something that will probably never be anything but noise. This is pretty much the same reason I don't put in a bunch of non-functioning UI controls that will hopefully have features attached in the future — my interface is meant to be practical, not aspirational.

[ Parent | on HN ]

Re:How I Judge the Quality of Documentation by Moru on Thursday February 27, 2014 @03:54PM (#7314983)

What about controlling the language from a cookie? Link to www.example.com/v1.5/import.html and end up with whatever language your browser specifies. A drop-down with links to all possible languages for this page so you can choose the one that fits you best. This enables you to have an incomplete translation in case you just don't have the resources to translate your whole documentation at once.

[ Parent | on HN ]

Re:How I Judge the Quality of Documentation by pseut on Thursday February 27, 2014 @09:43PM (#7316953)

Adding /en/ to the URL creates an expectation that there are translations in other languages.

[ Parent | on HN ]