2

At first, I thought that the people writing the code should also document it. But there are reasons why this might not be true. A person who is new to the code could ask the right questions which might be dismissed as "obvious" by the author.

My question is if there is an established practice (or practices), and what is the reasoning behind it/them?

  • Who would write the technical documentation if not the person who wrote the code? – Goose Aug 24 '16 at 14:46
  • I think that he's talking about technical documentation, and a choice between programmers. – BenPen Aug 24 '16 at 15:06
  • What do you mean by "established practices?" Are you asking if someone other than the person who wrote the code should refrain from documenting it, if the original documentation is inadequate? Absolutely not. – Robert Harvey Aug 24 '16 at 15:27
  • The new guy. ;) – JeffO Aug 24 '16 at 18:01
  • The only "established practice" I'm aware of is not writing documentation at all. Vendor SDKs with any documentation, let alone good documentation, are rare gems. – Kevin Krumwiede Aug 24 '16 at 20:20
5

It sounds like you're making the assumption that the documentation is written once and never updated. That may be true if your software never changes after it has been written, but that's probably not the case. Just like you can refactor your code to improve readability and maintainability, your documentation should also be in a format the promotes the ability to refactor. Your initial code authors are good candidates to write the initial documentation, but the people who maintain the code will also need to maintain the documentation. If the existing authors are still around and are answering questions from the new maintainers, someone (either the original authors or the new maintainers) should be assigned the task of making sure that the documentation is more complete.

The exact breakdown of roles and responsibilities depends on the organization. In some places, the developers are responsible for anything in the code file (API documentation and in-line comments) and the developers and testers support technical writers who write and maintain documents. In other organizations, the development team may write everything.

At the end of the day, it doesn't really matter who writes and maintains the documentation, as long as it is maintained. After all, wrong documentation is quite possibly worse than not having documentation at all.

1

In my experience the biggest problem with documentation is that it often does not paint the picture that matters, that lays out a high level model and then zooms in. If you let developers write documentation you get a repetition of code in natural language which is utterly pointless to both other developers and users alike. Documentation should be written in the course of analysis and design by analysts and designers, not as an afterthought by those who typed in the code. If you are lucky it is all the same person who is not too authistic and has some imagination. Unfortunately documentation is often something someone has to do before the project may be flagged as done.

And yes, it should be revisited which could be done by developers but the framework should already be there, created by people that know the why, the where from and the how rather than just the what. It is all about context, providing references to newcomers they can build their understanding on.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.