Project Management Stack Exchange is a question and answer site for project managers. It only takes a minute to sign up.
Sign up to join this community
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?
We differentiate between documentation for:
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.
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.
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).
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'.
