Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Why are you making normative claims about technical documentation? That seems to me more preposterous than anything written in the mentioned piece.


I'm not sure what you mean, the entire point of technical documentation is that it explains a technical subject, that is the definition of the phrase. You could add other things but then it stops being just that.


> the entire point of technical documentation is that it explains a technical subject

It also becomes incredibly boring. I hear what you're saying, but work has to be fun, at least sometimes.


No, it doesn't "stop being that". You're going to have to provide some sort of justification for that statement.


I said it "stops being just that." You removed the word "just" which changes the entire meaning of the sentence.


Sorry, one can read "just that" in two ways there, "it at all" or "only".

To carry on with your intended meaning, what is the problem if the technical documentation is more than just technical documentation? We're talking about a paragraph here, maybe 0.1% of the documentation. Are you making a claim that at some percentage of non-technical content the documentation becomes illegitimate?

I'm honestly just trying to understand what you're getting at.


Possibly I should have said "it stops being only that," that might have been more clear. The problem with making that 0.1% into something else is that people still get annoyed and distracted by it because it's not what they expected, and they complain, which is exactly what happened here.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: