Hacker News new | past | comments | ask | show | jobs | submit login

A programmer who writes their own documentation is like a barber cutting their own hair: Economical perhaps, but worse for anyone who has to look at the result.

And yes, if your audience is programmers, then ideally you can hire technical writers who can program, and who can speak to programmers, but failing that, technical writers who can get proofread by a programmer can also work.

Having a single consistent voice is what matters, and that comes from giving a person the responsibility to be that voice.




A programmer writing documentation is far from economical, since most of the time their time is worth more than technical writers.

It depends on the type of documentation of course, but if you work in a 50 person team and you want to document internal architecture or code structure, you better let the programmer that knows about the stuff write it.

First getting that technical writer up to speed about how everything is structured, the little implications etc, is pretty insane. It's like that phone game where you tell one person something, and then that one tells the next.


> A programmer writing documentation is far from economical...

And then you go on to explain a way that it is more economical; Time is also an important economic consideration.

> First getting that technical writer up to speed about how everything is structured, the little implications etc, is pretty insane. It's like that phone game where you tell one person something, and then that one tells the next.

No. That's what happens when you have a non-technical writer do technical writing. I wouldn't have felt like I have to say this but just because someone has "technical writer" in their job title doesn't mean they can do that job.


Yes, but they didn't do that job.

If my colleague programmer works a week on refactoring some code, I honestly have no clue what was changed. There is only 1 person who actually knows what and why.


I don't believe you can have 50 people producing knowledge and checking in code that nobody ever looks at or reviews, writing documentation that all 50 are expected to know, and have even a good portion of that 50 people understand it well.

I also think that if you have developers working for a week without anyone who knows what they're doing you have a management problem.

We might be talking past each other, and I might not understand exactly what you're saying.




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

Search: