Project documentation is crucial on detailing what a project consists of, how an ordinary user needs to navigate, what type of functionalities are still in progress or have been completed, as well as how the code is structured.

In a previous article, I have written about the importance of documentation and its role in project management. If you are not familiar with my previous article or the role of documentation, then I suggest reading The Important Role of Documentation first before continuing this article.

In this article, we will be expanding on the management of project documentation on a regular basis.

In most instances, a project would consist of two types of documentation:

1. User Manual
2. Technical Manual

1. User Manual

The User Manual is a document intended for users that need to be onboarded to a project, which can include users that need to use the web application / website for admin purposes or a developer that needs to know how to access the different screens for when they need to implement new features and thoroughly test code.

A basic example of how the document would be structured is as follows:

• Document Details (Purpose of document and who prepared it)
• Version Control (When document was updated, who updated it and change description)
• Document Contributors (Who the contributors to the document are and their role)
• Content Index
• User Type
  • Nav Section
    • Screen Name
    • Screenshot of specified screen
    • Action on how to access screen and brief description on what user can do on screen
    • Permission Required
      • Screen linked to main screen

  As you can see in the example above, there are different tiers on how the User Manual can be structured. Of course, it is not expected for everyone to follow this structure since every project is different and people have different ways on structuring information.

  Some sections, like permissions required, might not be present since there are projects that don’t always allow the user to choose which permissions can be given in the front-end.

  In my personal opinion, this structure helps to keep track on which paragraph belongs to certain screens and users, especially if the user manual exceeds over a hundred pages.

  To ensure that this document is up to date, the developer that oversees the User Manual must do the following:

  1. They will need to check if any new screens have been created or if an existing screen’s layout has been updated.
     • If a client requests a change or has planned for a new screen to be created to serve a specified function, the developer must update the action description of the specified screen and make a screenshot of what the specified screen looks like.
  2. They will need to make sure that all user type sections properly reflect the current state of the project.
     • When changes occur on the project, the developer needs to confirm if any changes include the creation of a new user type. If a new user type has been created, they will need to consult with their colleagues on which specific screens the new user is allowed to access.
  3. When updating the User Manual, they will need to ensure that the positioning of content and structure of the document is readable.
     • When the developer updates the document’s contents, the positioning of the paragraphs and screenshots change, which can sometimes negatively affect the of readability of the document’s contents. The best way to improve readability is to first update the index of the document, which will update the structure of the index.
     • If the structure of the index is not properly organized, then the developer needs to update it to be like the example above. If the screen’s action description is cut off in the middle of a sentence, then they will need to add spacing so that the entire paragraph can be read on the same page.
  
  
  

  2. Technical Manual

  
  

  The Technical Manual is a document that is intended for developers that need to be onboarded to a project, where they will be able to view detailed descriptions on each screen’s function, code reference and dependencies.

  Similar to the User Manual document structure, the Technical Manual structure is as follows:

  • Document Details (Purpose of document and who prepared it)
  • Version Control (When document was updated, who updated it and change description)
  • Document Contributors (Who the contributors to the document are and their role)
  • Content Index
  • User Type
    • Nav Section
      • Screen Name
        • URL – URL Address of Specified Screen
        • Function – Brief description of specified screen’s function
        • Description – A detailed description of what the screen consists of and what the code is doing
        • Code Reference – A link to the specific file that hosts code responsible for the screen’s functionality
        • Dependencies – Lists the screens that are needed to access to the specified screen.

    The only difference between the User Manual’s structure and that of the Technical Manual, the Technical Manual does not have any screenshots and the details such as function and code reference are written in a table, which makes it easy to read.

    To ensure that this document is up to date, the developer that oversees the Technical Manual must do the following:

    1. They will need to check if any new functionalities have been added or existing functionalities have been modified
       • Similar to the User Manual, if any new screens have been created, the developer will need to add it to the technical manual as well. However, if a screen’s back-end code has been changed to an existing screen, the developer will need to write what the modified and new functionalities do as well as link to the files that consist these changes.
    2. They will need to make sure that all information on the project’s development properly reflects the current state of the project.
       • When changes occur on the project, the user will need to check if new users have been added, similar to the User Manual. Detailed descriptions of each screen can vary since certain permissions only allow each user type to interact differently on the same screen.
    3. When updating the Technical Manual, they will need to ensure that the positioning of content and structure of the document is readable.
       • Similar to User Manual, the developer will need to make sure that the content is properly structured and readable.

    If possible, I would recommend updating the documentation after the new features and adjustments have been made. Of course, it all depends on the planning of the project.

    If documentation is not regularly updated, it will lead to a large stack of work, which will involve time consuming tasks. These would involve accessing all available screens and discussions with colleagues on what the code is doing.

    I hope this article has been very helpful