In software engineering, the documentation is essential: it provides all the necessary information for a better understanding of the software.

It was observed that a high number of projects fail because of poor documentation. If the project manager for instance doesn’t write down all the different aspects of the project plan some details can become unclear for the rest of the team.

Knowing that the documentation can be used internally or by the customers either when the project is under development or already in use, it is very important to have it knowledgeable. Modern manuals describe each and every feature of the software with more than a text: screenshots, charts, diagrams… they are usually part of the description.

One of the characteristics of a software documentation is that it can be divided in two main categories:

·      Process documentation: it covers all the necessary steps to complete a process and serves as a reference. 

It includes project documentation such as project plans, test schedules, reports, meeting notes…

·      Product documentation: it describes the product that is being developed and provides instructions to be able to use it.

It includes system documentation such as architecture descriptions, program source codes, FAQ’s and user documentation such as tutorials, user guides, installation and reference manuals…

Companies used to handle an unstructured documentation, but nowadays it is recommended to move to a structured documentation which provides significant advantages:

·      Improve content management

·      Easier and more secure process of versioning

·      Documentation more flexible and easier to modify or update

The documentation provided covers different aspects and can be helpful if it is structured. As an example, the fact that customers can find the information needed in the right document, on their own, decreases the number of support ticket.

This why we decided, in HPS, to move to a structured documentation, which will improve the users experience. To be able to achieve this transition, we used the CMS componize, that is known for the optimization of the authoring, management, and publishing of high volume documentation.

Then, we divided the different steps in two main groups:

On one hand we worked on the writing and conversion of the existing documents from Word to DITA.

On the other hand, focusing on the user experience, we worked on the definition of the metadata, taxonomy, synonyms and groups.

Among the metadata used to organize the content, a list of all HPS products and a subset of the components is available. 

Metadata can also be used to classify each document: deployment guide, functional description, installation guide, user guide…

Regarding the taxonomy of the business, we identified all the keywords of the business by browsing the existing documents. The idea was to organize it following a tree structure with synonyms, specific and generic terms. This taxonomy enables an article to identify directly the product and the context in which it is used.

One of the impacts on the client is that he can be more independent. Since the information is available online, he can access it directly, in a quick way.

We have seen that the software documentation was necessary and that it was strongly recommended to have a structured documentation. However, it is important to make the change step by step, involve the teams concerned and choose the right tool.

To know more about HPS and our suite of solutions please contact  sales@hps-worldwide.com