Documents should be written by the skilled programmers?

Question

Hi All:

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

Your group should create a software development process that defines how you go about developing your software products. Part of that process would define the documents to be written, and in my experience, all members of the development team share in the documentation process -- It can (and should) be a learning process.

Your software development process should define other topics as well, such as code reviews, unit testing, configuration management, etc.

There are lots of examples of processes, from very light to very heavy on the web.

Answer 2

You're not wrong, but fact is that documentation doesn't make money. If anything, poor documentation can increase revenue because you've ensured that clients will need your support contract.

Documentation is also a pain because in theory it's supposed to be done before development, but in reality things change so it's really only worth creating/updating after a major version release.

Ideally, the author should be the business analyst, not the developer.

Answer 3

The important questions to ask about any potential documentation is what is the goal, intended usage, and expected frequency of usage of the documentation? You mention helping a fresh man, but in practice, is reading the documentation faster and more efficient then getting a walkthrough from another developer? A walkthrough takes time from the other developer, but likely far less time then writing a document would.

Documentation with a strong business case and ROI over alternative options makes sense to create, but there are likely less cases of that then you imagine, and creating documentation without having a clear answer to my initial questions will guarantee you don't get the ROI for it.

Answer 4

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.

Answer 5

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 (i.e 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, its also helpful to the QA process.

Answer 6

Another way of looking at the documentation is for CYA purposes. If you ever have the misfortune of being in a project, where the leadership does not generate documentation, then blame for the bad code can go to you. Unless you protected your self with documentation.