Development Documentation Style Guide
English | Translate this article...
This article describes the best practices followed in Openbravo when writing documentation for development projects. It explains the documents required, their utility, their relationships as well as some good examples of each.
Please also check Documentation Style Guide article for syntax recommendations.
The project life cycle
The life cycle of a project involves the following steps:
- Requirements gathering. Projects starts from a list of requirements provided by a customer, a business partner or the CTO. This list describes, briefly most of the times, the needs for an extended or a completely new functionality. It is important that this list is prioritized in order to address first the most relevant items.
- Functional specification. The functional specification extends the list of requirements into detailed functional requirements, adding user stories, business processes and mockups. The functional specifications are the base for the technical documentation (design) and the QA test cases.
- QA test cases. Functional test cases are written based on the functional specification document, covering all the functional requirements described. These test cases are then executed and validated by the Quality Assurance (QA) team.
- Technical documentation. Based on the functional specification, the technical documentation describes the technical design of the software artifacts that will code the desired functional requirements.
- Development. The technical design is used by the developers to code the functionality required. Developers are in charge of reporting the development status in a separate article.
- User Manual. New or extended functionality is incomplete without an user manual that helps the end user to discover and get familiar with it.
A main (landing) page for each project has to be created. This article gives an overview of the project and provides some information about the development (developers involved, issue in the issue tracker - if any -, Forge project - if any - and development branch link). It also provides links to all the related documents, both project documentation and existing documentation or related papers.
This main article has to be located in http://wiki.openbravo.com/wiki/Projects/My_Project_Name (for Openbravo developers) or in the Wiki of the Forge project.
Wiki code example:
== Introduction == This project aims to cover this functional gap. * Leader: John Smith <john.smith at mail.com> * Feature Request: [https://issues.openbravo.com/view.php?id=xxxx issue_number_in_mantis] * Forge project: [http://forge.openbravo.com/ Link to the project in Openbravo Forge] * Development branch: [https://code.openbravo.com/erp/mods Link to the code repository in Mercurial or Openbravo Forge SVN] == Documentation == * [[Projects/My_Project_Name/Functional_Specification |Functional Specification]] * [[Projects/My_Project_Name/QA_Test_Cases |QA Test Cases]] * [[Projects/My_Project_Name/Technical_Documentation |Technical Documentation]] * [[Projects/My_Project_Name/Development_Status |Development Status]] * [[Projects/My_Project_Name/User_Manual |User Manual]]
Examples of landing pages:
This document lists all the initial requirements provided.
This list can be written down in a Wiki article or collected and stored in an on-line spreadsheet.
Examples of requirements sorted lists:
The person writing the functional specification has to properly describe users and profiles, business processes, users stories and, the most important, functional requirements based on the business processes (properly listed and sorted in tables) as well as clear user interface mockups (a picture is worth a thousand words). Clear functional specifications are also the base for QA team to write good test cases.
Please find detailed information about each of the functional specification sections in the Functional Specification Style Guide article.
Examples of functional specifications:
Other Functional Design Specification Document templates:
QA test cases
Quality Assurance test cases have to cover all the functional requirements described in the functional specification.
These test cases can be written both by the developer or by the QA team.
Examples of QA test cases:
Based on the tabled functional requirements, the person writing the technical documentation is in charge of choosing and describing the artifacts (windows, tables, callouts, triggers, procedures, ...) that will result in the desired functionality. Pieces of code can be included for a better understanding.
This way, one functional requirement can lead to several artifacts (for instance, coding a new window will require a table with X columns plus a callout plus a display logic) which will be described in different sections of the technical documentation.
Summarizing, there needs to be a clear link between the functional requirement that we want to achieve and the technical design of the components that will code this requirement.
Examples of technical designs:
The developer has to find in the technical documentation enough information to start coding. A good way to monitor the evolution of the development is the development status page. Here, we link the commits that the developer does with the artifacts (components) described in the technical design. An artifact can lead to several commits.
Examples of development status pages:
Finally, the user manual describes the usage of the extended or new functionality in a way that non-technical end users can understand it.
Examples of user manuals:
It is important that the project documentation keeps the consistency all over the cycle. This means that, if a new requirement is added or modified by the customer, the change has to be reflected in the functional specifications as well as in the technical documentation, the QA test cases and finally in the user manual.