I'm working on optimizing the process of documentation on the projects in IT company. The issue is that right now the company has documentation when the project is started but then they don't continue to add details about the new functions which they add. Also, I think there should be a difference between documentation for managers and developers.

What tools do you use for that? What best practices have you seen?

  • 1
    Hi, welcome to pm.se! You have different questions on the same post, so let's break them down. To keep consistency on documents for long term projects, you can refer to Maintaining consistency over documents. There's other questions on your post such as "should documentation be the same for managers and developers?" (which is a good question that I found no dup here so far) and "What tools could help to maintain documentation consistency?" (which would be offtopic, but there's some good tips on the linked question mentioned earlier). Please review.
    – Tiago Cardoso
    Feb 24 '19 at 11:41
  • 1
    The title asks about documentation on Long Term Projects; the body of the question asks how you maintain project documentation during the project (no mention of project duration). Which question do you want answered?
    – MCW
    Mar 28 '19 at 16:14

We differentiate between documentation for:

  1. Developers: This goes right in the source code and will be stored in Git. Whenever a function is added or updated, some "text in green" (our wording for developer documentation) has to be added. We write not only details & decisions about a function to it, we add additionally the reason why a decision was taken. Just think about the typical W-questions. This is a lot more effort to write it, but it helps especially in long term projects a lot.

  2. Managers: Strategic Dokumentation is widely created in Evernote with objectives, use cases and other business related information. We add not only text but also lots of charts, images, references to the web and other stuff. Everything is being tagged extensively. Over the time we link many documents with others which results in long term projects in an extensive business documentation.

  3. End users: The user documentation is written in Asciidoctor https://asciidoctor.org which is basically a super fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more. Asciidoc is almost as easy as simple Markdown but with lots of chances for a single source publishing. BTW: I am not associated with Asciidoctor - I just love it! Of course; the sources, images etc for the documentation is stored in Git as well. We try to keep the text files as modular and small as possible in order to keep the maintenance issues as low as possible.

If you are interested in our documentation results just have a look: https://www.projectwizards.net/en/support/documentation (in this case I am indeed associated with the company. If this is not allowed here please let me know, I will remove the link for sure and immediately).

  • 1
    Welcome to PMSE. As long as your Answer actually attempts to answer the Question and as long as you disclose the nature of your affiliation to a linked product, then, yes, including a link to a product is allowed. This one seems fine to me.
    – Sarov
    Mar 25 '19 at 15:23

I think Frank's answer is great, but I will add one further addition. The person/group who uses the documentation is accountable for its upkeep. That doesn't necessarily mean they are the ones who do it, but their manager needs to champion the effort.

One of the issues that keep documentation from getting updated is that it is often dependent on someone who is no longer working on that project and any time spent takes away from the time they have to spend on their 'day job'. So it gets put on the back burner until they get some 'free time'.

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.