5

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?

  • 1
    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
  • 1
    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
6

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.

2

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.

1

Should developers or other people write (technical) documentation?

It depends:

  • I would write API reference with the code. This means the developer would write it along with the code and it might be part of the source code (e.g. in comments). Putting this in the code has the additional advantage that the documentation gets updated along with the code.
  • As for introductory material, e.g. tutorials, this might better be written by people with experience with this. This might as well be someone who has experience with teaching and / or giving support to the typical user base.

A quote from ReadTheDocs Documentation Principles:

"In the documentation process, include everyone from developers to end users.

Integrate documentation into the standard workflow of developers, and seek to reduce silos that solicit documentation from only a subset of the software’s contributors. Developers and engineers are the people with the best access to in-demand information, and getting them to document it will help foster a culture of documentation."

Some other points:

  • In any case, a collaboration of several people would be better than one person. If you write documentation with the same tools as the software, you might have a review process for reviewing the docs as well as they are being submitting as pull requests / merge requests.
  • Decide on the source of the documentation (e.g. Markdown, reStructuredText etc.) and a toolchain for contributing. This will make it possible for several people to work on the documentation and keep it up to date. Some projects keep the docs source in the same repo as the code. Example (SaltStack: docs are rendered on https://docs.saltstack.com/, are written in reStructuredText (.rst) and can be edited via "Edit me on GitHub", source is in GitHup repo https://github.com/saltstack/salt/tree/master/doc)
  • If you have several people documenting (and in any case), it is advisable to put down some ground rules. This will prevent unnecessary discussions and make the documentation more consistent. This is often done in the form of a style guide. The style guide should addresses points such as:

    • Spelling rules (e.g. title capitalization)
    • Formatting rules (if any)
    • How to address the reader, e.g. adress them with "you ..."
    • Write in a more formal style
    • etc.
0

The original developer is in the best position to write technical documentation, but there are reasons why they wouldn’t:

  1. The developer produces excellent code and rubbish documentation. Then it is better for everyone involved if they spend their time to write excellent code, not rubbish documentation.

  2. Hiring a person to write the documentation may be cheaper, and doesn’t slow down production of code.

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.