How to document openbravo vertical solutions

Contents 1 Introduction 2 Forge Project 3 Openbravo vertical's User Guide 3.1 User Guide structure 3.2 User Guide generation 3.2.1 Screen References Generation 3.3 Where to upload the User Guide 3.3.1 Openbravo Wiki 3.3.2 Openbravo Sales Force 3.4 User guide readiness communication 4 Implementation

Introduction

This document is intended to be a guide on how to document Openbravo vertical solutions such as Openbravo for CoWorking or Openbravo for Retail.

The main objective of the Openbravo vertical documentation must be to provide a global view of the vertical solution provided, therefore the user is able to configure and use the vertical solution as a whole.

Openbravo vertical solutions might consist on a template that can contain:

• modules which implement vertical solution specific elements such as new windows
• modules which modified Openbravo application dictionary elements
• and Openbravo application dictionary elements.

Therefore, it is required to:

• document each module separately by making clear what is vertical solution specific and what it is not
• document the vertical solution template by giving a global view of the vertical solution provided
• and to take Openbravo existing documentation of the Openbravo application dictionary elements included in the template as such

Forge Project

As any other module or pack an Openbravo vertical solution template requires a project to be created in the Forge.

That project needs to be linked to a wiki page (wiki.openbravo.com/wiki/Projects/Project_ShortName) with below structure of information:

• an "Introduction" section that:
  • describes high level the solution provided
  • and the business process/flow that is being addressed.
• a "Documentation" section that:
  • includes a technical oriented document that details the content of the template
  • and includes the vertical solution documentation that is the "User Guide".
• a "Releases section that list every new release of the solution.
  The vertical solutions release notes need to have the same structure as Openbravo 3 Release Note. Find an example here
• and finally a "Related projects" section that includes a link to the Forge project of every module contained in the template.

Same way, every module that is part of an Openbravo vertical template also requires a project to be created in the Forge.

That project needs to be linked to a wiki page (wiki.openbravo.com/wiki/Projects/Project_ShortName) with below structure of information:

• An "Introduction" section that describes high level the content of the module as well as the feature/s provided
• A "Documentation" section that includes below documentation:
  • a "Functional Specification"
  • a "Technical Specification"
  • and a "User Manual" of the module that explains basically:
    • how to install it
    • how to apply the datasets if any
    • how to configure it
    • and how to use it

Openbravo vertical's User Guide

This section focus on the main Openbravo vertical solution document that is the "User Guide".

This section describes how to approach below listed aspect of it:

• the structure of the user guide
• the generation of the user guide wiki page
• the places where the user guide needs to be uploaded
• the communication of the readiness of the user guide

User Guide structure

Overall the structure of Openbravo vertical's user guides need to be the same as the Openbravo 3 User Guide structure, that is from the "Generic" to the "Specific".
In other words, from the global vision of the solution to the configuration and usability of a particular process and the explanation of a given window and tab.

Anyway, every process of a vertical solution needs to be put in the context of a business flow.

It is also important to remark that the Openbravo vertical's user guides need also to explain clearly where is explained what, in other words where the configuration of a given business flow can be found same as its usability.

The structure of the Openbravo vertical's user guide has a lot to do with the generation of the user guide as described in the next section.

Finally, the Openbravo vertical's user guide needs also to have an appendix which might list a Glossary of terms (valid for a given business activity type) and show all the vertical solutions screens.

User Guide generation

The user guide wiki page should be generated from the Openbravo vertical template under a given "Namespace" same way as for the Openbravo 3 User Guide that is generated from the Openbravo 3 application dictionary.

It is not possible to directly edit the User Guide wiki page of Openbravo 3 but to document in the "ManualDocs:..." available, as explained below:

"Edit this page" wiki link allows to edit the Openbravo 3 User Guide.

Once done, the image below shows what has been generated from Openbravo 3 application dictionary that at the highest level is the Openbravo 3 menu:

That generated wiki page has two ManualDocs:

• the ManualDoc:Main (Openbravo Admin) which includes the manually created Openbravo 3 User Guide documentation of sections 1 to 4, as shown in the image below.
• and the ManualDoc:Main Appendix (Openbravo Admin) which includes the manually created Openbravo 3 User Guide documentation of sections 6 to 8, as shown in the image below.

Moreover, inside each Openbravo 3 application area, i.e. Sales Management, there is another ManualDoc, i.e. ManualDoc:SectionSales Management(Openbravo Admin)

that allows to document what is shown in the image below that is the two business flows which can be executed within the Sales Management area, including an explanation of what it is needed to configure and to execute them:

Going back to Openbravo vertical solutions, the CoWorking template includes:

• CoWorking specific elements such as the "Contracts" window
• and below Openbravo 3 application areas which are also required:
  • General Setup
  • Master Data Management
  • Procurement Management
  • Sales Management
  • Project and Services Management
  • Financial Management

CoWorking specific application dictionary elements need to be documented in the corresponding "ManualDoc:.." sections that will be automatically generated for each CoWorking element of the template.

Openbravo 3 application dictionary elements included in the template do not need to be documented once more as they already are. The content of those sections needs to be taken from the Openbravo 3 User Guide, and the corresponding "ManualDocs" of the Openbravo 3 Application Areas.

Overall this approach will require an additional documentation effort whenever the same window is used for Openbravo 3 and it is also used slightly modified for the Openbravo vertical solution.

In that case, it will have to be clearly explained what is new for the vertical solution, for instance new fields in an existing Openbravo 3 window, by having into account that the rest is simply part of the Openbravo 3 solution.

In that case, it will be possible to flag an application dictionary element to use a different "ManualDoc:..." than the default one.

Screen References Generation

Same way, it is required to generate the screens of the windows included in the corresponding vertical solution template, including a list of all the fields.

Those images can be used to properly illustrate the "Manual:Doc.." related to a given vertical solution element such as a window.

An example on how this works is shown in the image below.
The generated image WS800249.png is the one to show in the "ManualDoc:T800249", that is the "Requisition" header window.

Where to upload the User Guide

The places where Openbravo vertical solutions user guide needs to be uploaded are:

• the Openbravo Wiki main page
• and the Openbravo Sales Force

Openbravo Wiki

It is required to remove below links from the "Introduction" section of the Openbravo wiki:

• Openbravo for Retail Configuration Guide
• Openbravo for Retail Web POS User Guide

Until a new Openbravo for Retail User Guide is created, the two documents above mentioned together with any other Openbravo vertical's user manual needs to be placed in a new section named:
"Openbravo Verticals"
that needs to be located between the current sections:

• Documentation
• and Openbravo Projects

The section Openbravo Projects needs to be clean up therefore its final content can be similar to the one described below:

"Openbravo is 100% modular. A module is a piece of additional functionality that can be deployed optionally and independently on top of Openbravo.
Examples of modules include additional reports, additional windows, connectors, and content packs (translations, chart of accounts, list of tax codes, product categories, etc).
For more information on creating modules, please see the Developer's Guide. Modules are installed from the Module Management window within Openbravo itself.
Projects to deliver Openbravo modules are hosted on the Openbravo Forge.
The Openbravo Exchange is the marketplace for published modules."

The new Openbravo Verticals section needs to:

• clearly define what an Openbravo Vertical is
• list the Openbravo verticals available
• and add a link to the Openbravo Verticals relevant documentation such as the user guide.

Openbravo Sales Force

There should be a new section under "Resources & Assets" // "Delivery Materials" named "Openbravo Verticals Documentation".

That new section needs to be placed just after the current section "Openbravo 3 Documentation".

That new section needs to include all relevant Openbravo verticals documentation such as the vertical solution user guide.

User guide readiness communication

The product manager of the Openbravo vertical solution needs to create a blog post to be published in the Openbravo Planet.
The blog post needs to communicate:

• the availability of the vertical solution user guide as well as where to find it
• the reasoning behind the user guide structure and content
• where to find what within the user guide
• where to find the content of the vertical solution template
• and where to find the specific user manuals of the modules contained in the vertical solution template

Other type of communication to be defined.

Implementation

This section list and briefly describe the tasks to execute to implement what is described above in this document:

Task Owner: CoWorking PM

1. CoWorking Forge Project as per section Forge Project of this guide.
2. CoWorking User Guide documentation
3. Creation of a Blog Post to communicate CoWorking User Guide availability.

Current status: In progress

Task Owner: Retail PM

1. Retail Forge Project documentation as per section Forge Project of this guide.
2. Retail User Guide documentation.
3. Creation of a Blog Post to communicate Retail User Guide availability.

Current status: Not Started

Task Owner: Platform team

1. CoWorking User Guide wiki page generation under Namespace "CoWorking"
2. Retail User Guide wiki page generation under Namespace "Retail"
3. CoWorking Screen References generation.
4. Retail Screen References generation.

Current status: In progress

Task Owner: Documentation Lead

1. Openbravo wiki main page updated as described here
2. Openbravo Sales force updated as described here

Current status: Not started