Hi, I am Döndü from Bestcloudfor.me which is a technology company. I am working as a Product Owner. Here I want to mention how we can prepare project documentation.
Before starting the exact point of how to do it, firstly I want to talk about what is it briefly.
What is the documentation?
When we talk about the documentation, many ideas come up with your mind because we use documentation in many areas. We use the documentation in our school homework, for our staff at work, for our project when we present to our stakeholders, etc.
The first mean of documentation came to the mind, basically, it is a material that provides official information or evidence or that serves as a record. From this point of view, this article also documentation.
As I said before there types of documentation, here in my article I will mention software documentation, what is it, and how to prepare it.
What is Software Project Documentation?
Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it and may mean different things to people in different roles.
A software project documentation should consist of the following classifications.
As Bestcloudfor.me, we serve DevOps services by doing transformation to the cloud, migration, and managing your infrastructure. We also have prepared project documentation to deliver works to our stakeholders. Here, we have been preparing one project documentation by merging the product and process classifications. Let’s start to mention how to prepare project documentation in Bestcloudfor.me.
How to Prepare a Project Documentation in Bestcloudfor.me
Key Values of Our Documentation
The documentation should be included in the titles below; who is the audience, what is an executive summary of the project, what is prerequisites, and glossary. And additionally, it should be included in the table of content & index.
Let’s start explaining each key-value one by one with their importance.
Who Is Our Audience?
When preparing documentation we should first define our target audience, who are they, what is their knowledge about the topic or what is the level of their interest in the project, they are working for which department, etc.
After defining our target audience, we should prepare the strength level of content, and finally, we should state the target audience into the documentation in the beginning part. The example of the audience part can be written as follows:
It is the summarize of the project’s key concepts, here we should state basically what was the main purpose of the project and why we worked on it and how we did it. You can see an example of an executive summary as follows.
This part is written to state the importance of competency before reading this document. Here we should suggest some prerequisites to gain the competency. It might be related topics to read, or maybe it is another document that you have prepared and delivered already to your stakeholders before this document. You can attach the previous one to this document. Or, It might be a different page from a website regarding your topic. You can see the example of the prerequisites part as follows:
You should add your unknown words to the glossary part. You can create a table, you can link the words from a related website to show in the document. Or you can apply another method. You can add the glossary into the beginning part of the document or it can be placed at the end of the document. You can see an example of the glossary part as follows:
Table of Content & Index
It is the order of your main and subtopics with the page number.
- It allows readers to turn to the specific page they want in the document.
- Find keyword specific topics or details by checking the index.
You can see the example of the table of contents and index as follows:
Trend Topics for Quality of the Document
You can increase the quality of your document by using the information below.
Write your project name briefly which is related to the project scope. It should be on the first page of the document.
The Flow of the Scope
Titles should reflect the logical order of the scope (before and after) and also it should be shown in the table of content and index part in the right order.
Adding Header & Footer
The document should include the header as a logo of your company and also the footer as page number for example.
Adding System Architecture
You should add the system architecture of the project and it must reflect the scope of the project.
You should add the kick starts part to your document, readers need to find the list of software to install to prepare yourself before starting running the document.
As you know it is a software project and of course, it will have some important technical details for the stakeholders. So when preparing the documentation you should add these details into your document. These may be the number of servers with minimum requirements or versions of the software.
SS and Diagrams
It will be useful to support your documentation with screenshots and diagrams. However, the most important topic here is that these screenshots and diagrams should be related to the main topic.
The Right Definition of the SS’
Giving the right definition to the SS is as important as adding them to the document. Doing the missed or incorrect explanation will direct the readers in the wrong way. So, your explanation for the ss should really represent what should do on that screen.
Explanation of the Topics
When you want to mention about the flow of a topic, you should start with doing explanation firstly, do not start executing the flow directly. Giving some details in the explanation part will be helpful for readers to understand your flows.
Choose Your Side!!
You should select the right modal verb form should/have to/must for directions. Readers need to do that step, the reader can understand that is a mandatory step or it is an optional one. And starting with “You” when writing a sentence provides sincereness between you and your target audience.
Related to Document
Some additional points as follows:
- Chose the language according to your target audience.
- Define a format for the naming of the documentation.
- Apply the significant fonts and size for every part of the document.
- Do versioning for the changes after reviewing the reader.
The last most important part of the document is doing quality checks before delivering it to the stakeholders. You should check for typos, misspelled words, and grammatical issues. If the document passes the quality check then you should run the document from the beginning by thinking an end-user.
Thanks for reading, I hope it will be useful for you.