Documents should be written by the skilled programmers?

Question

I always think document is really important for a project and a team and should be written regularly and detailedly. It can make things go in parallel without always asking the skilled programmers here and there. But truly I find many developers(even leaders) don't put so much attention to documents and just take them for granted, which makes me feel bad.

So is my attitude to documents right? Are documents are really important? How should I persuade the team leader to put more attention to the documents?

If documents are important, the second question springs up. Who should write the documents? IMO, they should be written by the skilled programmers like the framework creator(if we use our own framework), the important parts of project(like db schema, the whole architecture, etc.) and more.

The benefits are obvious, like helping fresh man, help maintaining and more.

So from my opinion, the skilled programmers(the definition here may be different) should pay more attention to the documents writing than code writing after the infrastructure is done.

Am I right about this point?

Thanks for your sharing about these questions.

Answer 1

You have several kinds of documentation, one of them is your responsibility:

Document each function, class, structure, member as you complete it

Ideally, you do this in a way that permits automatic extraction of source documentation (e.g. Doxygen). Just be sure to do it as you go.

As far as customer documentation goes, my beliefs are:

• Every development firm should employ testers
• Testers should contribute heavily to the documentation process

I've been with companies that simply will not pay in full for the final product unless it ships with complete and comprehensive documentation. 10% is usually held back just to ensure that the contractor has incentive to deliver all materials.

As far as testers go, they are really your best friend (or should be). They are the people who know how your software works almost as well as you do. And yes, I agree, you should have at least an outline of a programs functionality, this keeps you from going off on 'value add' tangents. It just makes sense to let the testers be the one to fill this in, then have the developers review it for accuracy.

You may even find your self saying "No no no .. it doesn't work that way .. the testers got this wrong ...", then you fire up the app to realize that they got it right :) In that aspect, it's also helpful to the QA process.

Answer 2

I think it is up to each team, but many times, programmers aren't skilled in writing documentation. That is why there are people like Technical Writers. The programmers should be involved in every step since they are the subject matter experts, but the writers should write.