View source | Discuss this page | Page history | Printable version   

How to document openbravo vertical solutions

Contents

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:

Therefore, it is required to:

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:

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:

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:

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:

User Guide Generated.png

That generated wiki page has two ManualDocs:

Manual Doc1.png

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

Sales Management.png

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:

Sales Management Index.png


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

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.

ManualDocT800249.png

Where to upload the User Guide

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

Openbravo Wiki

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

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:

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:

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:

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

Retrieved from "http://wiki.openbravo.com/wiki/How_to_document_openbravo_vertical_solutions"

This page has been accessed 2,474 times. This page was last modified on 25 June 2013, at 11:18. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.