How to properly document a feature

Contents 1 Introduction 2 Feature types 3 User Guide structure 4 How to properly document in the User Guide 4.1 Examples 5 How to properly document in the Release Notes 6 How to properly document an Advance Feature

Introduction

One of the Openbravo's goals is to create and maintain an excellent documentation set about Openbravo 3.

This how to article explains how you can properly document a new implemented feature in the Openbravo 3 User Guide.

Feature types

To properly document a new feature relies on the type of feature that is being implemented.
That can be a feature that just add a new field or checkbox in an existing window or a feature that add a new process in an existing window or even a new window, a new process, a new report or a mix of them.

Anyway, all of the above responds to an end-user or final customer need which implies that a real business process can be accomplished.

Therefore while documenting a new feature no matter the type or complexity it is, we need to get it documented within a real business scenario context.

User Guide structure

The user guide is split into several parts that goes from the "Generic" to the "Specific", in other words:

By "Generic" it is meant:

• the Openbravo 3 User Interface section which gives an overview of the navigation, grid and form editing, tabs, filtering and interface customization.
  • This section is aimed to help the reader to know how to navigate within Openbravo.
• the Business Flows section which describes a set of business flows that can be present in an organization or not depending on the nature of its business.
  • This section is aimed to help the reader to know which business flows can be covered and how by Openbravo
  • Each business flow has a link to the corresponding business flow diagram within the corresponding Openbravo application area.
• and finally, the Common Concepts and Processes section which lists and describes a set of concepts and processes with can be found more than once in Openbravo.
  • This section is aimed to help the reader to know which are the Openbravo common concepts and processes in a generic way.

By "Specific" it is meant:

• the Openbravo Application Areas section which list Openbravo functional areas such as "Procurement", "Sales" or "Finance".
  • This section is aimed to help the reader to know how to setup and use each functional area within the context of a given business flow, by explaining each tab and field of a window and by explaining each window, process or report.
• and finally, the How to section which contains a set of articles that document areas of special interest.
  • This section is aimed to help the reader to know how to achieve particular business goals in a manner supported by Openbravo.

How to properly document in the User Guide

Normally all of you document new fields added in existing windows or windows, processes or reports that were changed or that are added within the corresponding Openbravo Application Areas section.

It is very intuitive to find the place where to document windows, processes or reports that were changed or that are added in an application area for instance Procurement, as each application area
structure follows the Openbravo menu structure.

Even each application dictionary element, for instance a window such as the Purchase Invoice window, it is shown in the user guide and therefore documented split by the tabs it has.

However majority still forgets to update or at least to review for a possible change the Business Flows or How to articles sections where these windows, reports or processed are used.

This last step is key because according to our documentation concept each window is taking part of some business process.

In Summary, every time that you document a new feature remember to follow below detailed steps:

1. Review the Business Flow which could be changed due to the implementation of a new feature.
   For instance, let's imagine that a new window has been implemented in the Procurement Management application area.
   As a consequence of that either the Procure To Pay or the Supplier Returns business flows within the "Procurement Management" area might required also to be changed.
   Depending on the new feature you implement you might need to change the configuration part and/or the execution part of a business flow.
   Even more, it is recommended to start the documentation work by updating this part of the documentation first because it sets the context that is required later on to describe the window and the operations in this window
2. Review the list of How to articles.
   Each how to article starts with the configuration required before performing a given business scenario and then explains how the business scenario is executed.
   Depending on the new feature you implement you might need to change the configuration part and/or the execution part of a given business scenario.
3. And finally, review the Openbravo Application Area that change, specifically the Application Menu part, where you can find where to document the particular window(s) / report (s) / process (es).

Additionally, if you change an OB generic component such as the "Product Selector" you need to review the Common OB Concepts and Processes section.
In that section we describe only once common concepts and/or processes which can be used in many places in Openbravo.

Examples

Lets review few examples:

1. Return Materials

Return materials functionality manages vendor/customer returns orders, including the physical outbound/inbound of returned materials as well as the financial settlement for vendor/customer refunds.

This functionality can be considered complex as it creates new processes and new windows within Openbravo, specifically in the procurement and sales management application areas.

In regards of documentation this new functionality required:

1. the creation of two new business flows that are:
   Supplier Returns within the Procurement Management application area and Return materials and Customer Returns within the Sales Management application area.
   Both the "Configuration" and the "Execution" sections of each business flow above required to be changed.
2. and the explanation of specific windows such as:
   1. Return Reasons in the Master Data // Business Partner Setup application area
   2. Return to Vendor, Return to Vendor Shipment and Purchase Invoice windows in the Procurement Management application area
   3. Condition of the Goods, Return from Customer, Return Material Receipt and Sales Invoice windows in the Sales Management application area.
   4. Generate Invoices process within the Sales Management application area.
   5. Accounting tab of the Product window in Master Data // Product Setup application area.
   6. and finally Document type window in the Accounting setup part of the Financial Management area.

2. Quotations

Sales Quotations is a separate sales document with a separate document type and number sequence.

In regards of documentation this new functionality required:

1. to change the Order to Cash business flow within the Sales Management application area.
   Both the "Configuration" and the "Execution" sections of "Order to Cash" business flow required to be changed.
2. and the explanation of specific windows such as:
   1. Document type window in the Accounting setup part of the Financial Management area.
   2. Sales Quotation and Sales Order windows in the Sales Management application area

3. Accounting Schema renamed as "General Ledger Configuration" feature required:

1. to change the Period End Close to Financial Report business flow, specifically the Basic Configuration section.
2. to review and properly document the General Ledger Configuration window, former "Accounting Schema" window, as some of its tab where also renamed.
3. and finally to rename former "Accounting Schema" terminology as "General Ledger" all over those places where "Accounting Schema" terminology could be found, for instance the Financial reports under the "Analysis Tools" section of the Accounting application area.

3. "Open/Close Periods and Year Closing"

The main goal of this feature was to improve the usability of the "Open/Close Periods" and "Year Closing" processes.

In regards of documentation this new functionality required:

1. to change the Period End Close to Financial Report business flow, specifically the Execution section.
2. and the explanation of specific windows such as:
   1. the Fiscal Calendar, the former "Open/Close Period Control" window renamed as Period Control Log and the new Open/Close Period Control window, all of them in the Setup section of the Financial Management // Accounting application area.
   2. and the End Year Close window in the Transactions section of the Financial Management // Accounting Application area.

How to properly document in the Release Notes

Openbravo Release Notes includes a section named "What's New". That section includes a list of all the new features implemented in a given Openbravo 3 MP, for instance 3.0 MP18.

Each new feature listed in there needs to link to the place where it is documented.

To put the right link is in most cases tricky, mainly for those features which require several changes within the User Guide, for instance a change in an existing business flow or a change in existing windows.

Overall, the right approach is to link the new feature to the changed business flow where that change in functionality is being documented overall.

How to properly document an Advance Feature

An Advanced Feature is an Openbravo feature hidden in the default "Configuration Script" because it is not commonly used, however it is always possible to unhide an advance feature by using the "System Administrator" role.

There could be advanced features which require to unhide:

• a Window
• and/or a Tab
• and/or a Field

While documenting an advance feature you need to clearly state that the feature is an advanced feature as well as to list the Openbravo elements that need to be unhide to make this feature visible.

For additional information about this type of Openbravo features, please review the Advanced Features article of the Openbravo 3 User Guide.

For an example on how to properly document an advance feature, please review the Discounts and Promotions article of the Openbravo 3 User Guide.