Documentation is so important that no project should be considered as done without it. Well, at least it would be better if that affirmation was true all the time. Those who work on legacy projects understand what I said at the top of this paragraph.
No rarely you'll find yourself working in complete darkness, looking for information and data from old projects, and finding absolutely nothing.
That's the main reason I decided to share below some aspects that I consider important regarding project documentation as well as some tips and tricks making it easier to get started. Then you can make life easier for those that'll maintain the project that you're currently working on.
Documentation is all about future and collaboration
When you write down things you're working on, you're collaborating with you, in the future. Believe me, some point in the future you or one of your teammates will need to know how the different modules of a project interact, or why you'd chosen a library/technology instead of another one. I understand that code should be clear enough to drop comments out, but code doesn't show the big picture for those reading it.
For instance, imagine a scenario where you receive the task to implement a simple feature in an old system. So to get it started, you'll need to find its repository, the instructions to build it, a brief explanation of how it works, and about its architecture. You won't find that in code!
That kind of information is also valuable for the newcomers in your company and for your mates too.
It's a good idea to have a place (I mean a virtual one) where you and your colleagues can write down about you're working on - put everything there: repository URLs, build instructions, architecture diagrams, etc.
Documentation must be broadly accescible
Word and PDF are not good documentation containers. Of course, that doesn't apply for delivery documentation or any other kind of static doc, as a release note, for instance. Even with all recent efforts of Microsoft and Adobe on improving them editor/reader apps, it's hard to find what you are looking for on them, and also they weren't originally designed with collaboration in mind. Moreover, those kinds of files are shared through e-mails or instant messengers, so only peers involved in the conversation can easily access them.
Instead of docs and PDFs, prefer wiki or blog like tools. They usually provide versioning systems as well as embedded search engines, then it won't be hard to find old project docs and collaborate on them. Even bug/project tracking systems, as Jira or Bugzilla can help you and your team to keep track of project history and show you how you solved issues you'd faced during development.
README is your friend
I know: code maintenance is hard, and documentation maintenance is even harder! For that reason, a readme file is a good idea. Since it's near to the source code, you'll find it easy to maintain it. Modern versioning system frontends can interpret markdown readmes, so it's easy to enrich them with pictures, diagrams, bullets, etc.
Readme files can be a good start point, especially for coders. A good readme may contain a building howto, a description of the project, usage examples, and so on.
A diagram says more than a thousand words
Need to show how modules talks to each other? Prefer a diagram to explain it. You'll save time for those that'll read it.
Lazy about drawing them on an app? Do it on a whiteboard and take a picture. Mobile scanner apps may save some time drawing and can make them easy to read on collaboration tools.
...
I know that writing docs is boring and time-consuming, but it worth it. Keep in mind that people will work someday on what you're working on today, so they'll depend on what you left for consulting. Maybe code can describe itself, but projects no.
All that I said may seem to be obvious for you but you can't imagine how many times I faced a lack of documentation in my career, which reinforces the importance to talk about it.
Top comments (2)
Writing doc is boring and take a lot of Time !
So I created a Docker to build documentation according a specific theme from markdown to pdf. Now I can only concentrate myself on the content and not the style.
the purpose of this Docker is to build documentation accross CI/CD pipelines. So the doc can follow the code in the repo. it is also very nice when repo have automatic releases generated.
hub.docker.com/repository/docker/f...
Very good! I'll check it out. Thx for sharing