IT Project documentation format; best practices

See AMP Version

What is the most appropriate IT Project documentation format? And, what are IT Project documentation best practices in terms of format?

The question may seem strange because, for many, this question does not even arise. But on closer inspection, it deserves to linger; how should I document an IT project and with what type of format?

To highlight the challenge of an IT Project Documentation format, there are three factors to consider:

  • Object of documentation
  • Who is it for?
  • Who is it produced by?

What is the best IT Project Documentation format to use and, what are the best practices?

Answering this question is not that simple because without being infinite, the potential IT Project documentation formats are numerous:

  • Word file
  • Excel file
  • Visio file
  • Enterprise Architect file
  • RTF file
  • Markdown file
  • Balsamic Mockup file

At Analystik, we use all these different formats, here’s why.

 

Word and Excel file

Some documents must be shared with customers, for example, meeting minutes, requirements, and functional documentation. We, therefore, use for these documents a format accessible by all; Word.

As for the Excel format, we always use it to compile the “to-dos” following a meeting and for special cases like the definition and the functional documentation of a complex algorithm.

 

Visio file

Despite the fact that the capabilities of the Enterprise Architect software are more advanced, we decided at Analystik to use Visio for its simplicity and its wider distribution. We use it to schematize processes and to create our UML diagrams.

 

Markdown file

For the technical documentation that generally involves the entire development team, we have moved from RTF to Markdown format because this format is becoming more standard and publishers are more and more efficient. The benefits of this are the versioning (the editing tool keeps the version history) it provides and the comparison of versions.

These two formats, used within a development environment like Team Foundation Server (Team Service), manage check-in and check-out well and allow easy editing by multiple users.

 

Balsamic Mockup file

In the case of Balsamic, I would say that it is a love story at Analystik. It does only one thing but he does it so well and so easily. It allows us to make screen models that will be included in our functional documentation.

 

CONCLUSION

In this post, we described how we document at Analystik. In our next post, the third and last in the series, we will talk about how we save all this information.

Happy development project,

 

Denis Paul & Michel

Leave a Reply

Your email address will not be published. Required fields are marked *