Hacker News Reader

Comment by sjsdaiuasgdia | Hacker News Reader

When I read documentation, I'm not there to enjoy the experience. I'm there to find out how the documented thing works and how to use it. It's not a novel. I'm not there for entertainment.

Chasing readability without maintaining accuracy is a failure in the context of documentation no matter the motivations involved.

I'm not saying that readability can't be a consideration when making documentation. I am saying that if you discard accuracy in the process, you've fucked up quite badly.

This anecdote would likely be very different if the AI-modified version had been passed back to engineering for a review before sending it out.

View on HN

> I'm not saying that readability can't be a consideration when making documentation. I am saying that if you discard accuracy in the process, you've fucked up quite badly.

You're right to elevate accuracy to a high level of importance, but that is NOT ENOUGH if the thing is has poor readability. The audience has to be able to understand the document if the document is to be useable.

There's only a certain amount of effort anyone can deliver in producing a document. But if the author can't deliver readability, they need to follow up the document with a lot of support and/or get some help to make it useable.

I've struggled through some absolutely awful documentation over the years. I'll put up with incredibly broken English and other problems as long as the accuracy is there. Just last week I encountered a pinout diagram that used emojis to indicate which pins related to which data channel. Not a choice I would have made, and I found it made the diagram harder to read. But it was accurate - I wired it up per the diagram and everything worked as intended.

Documentation lacking accuracy is useless. It can be the most readable thing ever produced, but if it describes a different thing than what was intended to be documented, it's trash. Documentation that is hard to read but is accurate still has value.

Regarding "follow up the document with a lot of support" - did you catch the part of the anecdote where the author is having to deal with support requests because of the inaccuracies?

Reply on news.ycombinator.com