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

41–50 of 75 posts

Re: How I Judge the Quality of Documentation

#41

Post by rogerbinns »

susi22 wrote: post #23

ReadTheDocs [1] is by far the best platform to have documentation. The simple reason: Everything gets into an Elasticsearch server (sponsored by Rackspace) which means you get wonderful full text search (and faceting). See: http://read-the-docs.readthedocs.org/en/latest/search.html?q... [1] https://readthedocs.org/

Sadly they aren't useful if your documentation is more complex. For my project I do use Sphinx for the doc, but there is a prebuild stage where some of the API information is extracted from non-Python text files (C source). Another part runs the example code and captures it as RST. There are various other nuances like that.

readthedocs can't build that (make docs would work on my tree). I've contacted them several times to ask for how to proceed and never get an answer.

You can see my Sphinx doc not at readthedocs but at http://rogerbinns.github.io/apsw

Re: How I Judge the Quality of Documentation

#43

Post by jj00 »

I've been evaluating using a wiki for some of our documentation, with DokuWiki. It uses plain-text markup files, but also allows for some collaboration between users. I can see where it wouldn't be so hot on the version front, but I'm hoping that we can come up with a procedure to keep those text files in a repository.

Re: How I Judge the Quality of Documentation

#44

Post by avmich »

oskarth wrote: post #40

I agree with most of these, but this one stuck out. > I believe that translating documentation is a really important step towards helping people learn to program. Someone shouldn’t have to learn Programming and English at the same time. Really? Knowing English is pretty much a prerequisite for programming. Should all UNIX man pages exist in other languages too? That said, of course tutorials in other languages are us…

> Knowing English is pretty much a prerequisite for programming.

Emphatically no. You can be a brilliant programmer without knowing English. Of course, that doesn't say that knowing English somehow hurts.

I've met many programmers smart enough to learn programming to expert levels despite not knowing English and having to rely on whatever was available in other languages - sometimes that was plenty, sometimes they had to reinvent algorithms. At the same time I know other good programmers who were faced with the problem of learning programming and English at the same time and succeeded at that.

Re: How I Judge the Quality of Documentation

#45

Post by conductr »

I use most code from OS projects and I've always preferred good use examples. I see a lot of overly simple use examples which really give no direction for a new user(Apple ios examples). Any format works but list all the methods of a class. And list what arguments they accept and the acceptable types of each. And finally list what is returned.

I document my code as a business logic statement. Eg given credit card, process payment. I then write the validations in a way that reads simple and thus is documentation. If it's a complex line that takes more that a few seconds to parse mentally. I will write out what it does. That's pretty rare. Non programmers never see my code so that works just fine.

Re: How I Judge the Quality of Documentation

#50

Post by vacri »

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…

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 than 'everyone'. And what if the leading engineer in your field didn't document in that language? You'd be cut of from what they had to say.

A common documentation language functions as a technical standard, like IPv4. Sure, you can use your own standard, perhaps IPX, but you'll only be able to communicate with a much smaller group of people.

It's hard to get documentation written in the first place, let alone good documentation. Making it 'fair' by saying that documentation has to be effectively splintered into every native language is a sisyphean task.

As always, write to your audience. If it's a general tech audience, that means English. If it's Chinese engineers who don't speak English well, that means Chinese. But those Chinese engineers are going to have an easier time interpreting foreign documentation if it's all in one language rather than 50.

Post reply on HN