Development Documentation Style Guide

Contents 1 Introduction 1.1 The project life cycle 1.2 Documentation structure 2 Requirements gathering 3 Functional specification 4 QA test cases 5 Technical documentation 6 Development 7 User manual 8 Conclusion

Introduction

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:

1. Requirements gathering. The purpose of this stage is to collect market and customers (end-users) functional requirements, including statutory and regulatory requirements, into the Openbravo Roadmap.
   In other words, 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. User Manual. New or extended functionality is incomplete without an user manual that helps the end user to discover and get familiar with it.

Documentation structure

A main (landing) page for each project used to be created as a wiki article and related to the corresponding project in the Openbravor Forge.
This article gave an overview of the project and provided some information about the development (developers involved, issue in the issue tracker tool if any, and development branch link).
It also provided links to all the related documents, both project documentation and existing functional and technical documentation.

This main article had to be located in the openbravo wiki named as described below:

http://wiki.openbravo.com/wiki/Projects/Project_Name

Please review this wiki page as an example.

Nowadays, and with the aim of keeping desing and development documentation for internal use only, while external one is published in the Openbravo wiki, aha tool allows to structure and track all documentation required for a project as shown in the image below.

Internal documents such as technical specification and QA Test Plan are kept as google docs, while user documentation is published in the Openbravo wiki.

Requirements gathering

The purpose of this stage is to collect market and customers (end-users) functional requirements, including statutory and regulatory requirements, into the Openbravo Roadmap.

Openbravo product roadmap is intented to reflect Openbravo product vision that is based on:

• what our market claim, therefore our objective is to offer the preferred Commerce & ERP Platform for business where technological diruption is rapidly changing today's business paradigm.
• what we think it should be our value proposition, therefore our objective is to offer the preferred commerce solution for agile retailers as our retail solutions are based on an integrated, scalable and easily customizable and extendible platform.
• what we think it should be refactor to meet Openbravo standards or best code practices, which Openbravo is commited to implement.

For additional information, please review Product Roadmap Definition.

Functional specification

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:

• http://wiki.openbravo.com/wiki/Projects/EnhancedMulti-organizationSupport/Specifications-tmp
• http://wiki.openbravo.com/wiki/Projects/Project_Scheduling_Capabilities_Enhancement/Functional_Specification

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 either by the developer or by the QA team. In any case QA team will ensure that all test cases written as a part of a Feature implementation Test Plan, cover all functional requirementes to implement.

QA team uses Test Link tool to drive test creation and execution. See image below:

Technical documentation

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 relation 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:

• http://wiki.openbravo.com/wiki/Projects/Multi_Currency_Reports_Review/Technical_Documentation
• http://wiki.openbravo.com/wiki/Projects/XSQL_Insert_Update_Review/Technical_Documentation

Development

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:

• http://wiki.openbravo.com/wiki/Projects/Multi_Currency_Reports_Review/Development_Status
• http://wiki.openbravo.com/wiki/Projects/XSQL_Insert_Update_Review/Development_Status

User manual

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:

• http://wiki.openbravo.com/wiki/Modules:LoyaltyManagement/User_Documentation

Conclusion

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 agreed between the parties involved and reflected in the functional specifications as well as in the technical documentation, the QA test cases and finally in the user manual.

Categories: Templates | Community