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

Create a knowledge-team whose sole job is to take information from all the other teams, digest it, and make it available to the rest of the firm. Call it "corporate communications" or "internal marketing" or whatever floats your boat. If you can't get a proper department, at a minimum you can get a on-staff librarian who is a good technical writer who you can pass around the firm (as long as they have the ear of the CEO/COO).



In a programmer environment, this is impossible. A programmer will always need to document his own things for a simple reason: (s)he is the only one who really knows. Putting people in the middle of that who can barely understand all the details, seems like a lot of overhead for a worse deliverable.


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: