Functional Specification Style Guide
The Functional Specification Style Guide intends to be a brief document to explain how to create well formed documentation for all the projects to develop new features for Openbravo.
Please remember that the information available within the specification will be used for the following purposes
- to estimate the total amount of effort and the tasks that will be required to achieve the requirements in the specification
- to give the developers an understanding of the processes described and how to develop the solution so that it looks, feels, and behave as the business requires
Most developers do not have an understanding of what it is to work within an operational role in a business therefore the more information that can be relayed in the specification document that will help the developer to understand the business the better the solution will be. For this to be achieved the document should be treated as a form of educating the developer about how the processes are used and what the user will expect.
The more information you can give in the specification the better the results.
Please see below for an explanation for each section of the template
These are the points that the documentation almost has to cover. More points can be added depending on each project necessities.
The overview for the project will be a brief summary outlining the goals and reasons for the project.
Go into more detail here on how the implementation of this project will be used and why it is required in the business.
What is the scope of the project? How much functionality is it to cover and more importantly what it is not expected to deliver.
Any references that may be required for extra knowledge or information in regards to providing an accurate estimation on the completion time for the project.
This section of the specification covers anything that may affect the development or implementation of the solution. This is the place to put any potential problems or requirements that are not necessarily stated elsewhere in the specification.
With all projects there will be certain assumptions made regarding the development or implementation of the solution. Examples of these would be that all components should be translated into Spanish, or ??
In the project there may be elements of the solution which will have a dependency on outside issues or other designs. In order to implement or develop the solution these dependencies will need to be resolved or removed. e.g. resolving a licensing issue with a dependant library
Highlight here any issues which will restrict the development or the implementation of the solution.
Please explain any specific terms relating to the project that may not be understood by all involved. This would include industry specific terminology or abbreviations used in the specification document.
This is the main section into the Functional Specification document and it should be treated with an special care.
User roles & profiles
Explain the different roles that can use the new functionality and their knowledge related with computers.
Examples of possible user roles:
- Warehouse workers
- Typically these users do not have a high level of professional education and might not be computer literate. They tend however to spend a number of years with the same employer and after hiring they go through a few days of training to learn the processes within the warehouse. These users, therefore, need to be able to learn how to use the product in a few hours.
- Purchase managers
- Typically these users have a high level of professional education, are computer literate and receive training in the product and business process. These users perform purchase orders from the requisitions, they have to select the correspondent vendor taking into account the different variables that can take part in the decision: price, discounts, availability,...
- Generic employee
- These are users that work for the organization implementing Openbravo in a variety of roles and that are involved in a given business process on an occasional basis. Because of the infrequent nature of their involvement in the process, their primary concern is ease of use, defined as the ability to perform a new task without having to read any documentation.
Business process definition
A definition of the process is expected in order to know what business capabilities are supported.
A good approach to understand the problem is trying to explain it with real cases that happen in the real world.
User Stories are short, clear descriptions written from the perspective of the user about a feature they want and why.
A user story typically follows a simple, three-part structure often referred to as the "Role-Feature-Reason" template or "As a [type of user]... I want [some feature]... so that [reason]..." template.
Unless there are objective reasons due to the nature of a project not to include user stories, it is mandatory to include user stories for each type of user affected by the specific Functional Specification.
Functional requirements based on business processes
Use this space to provide detailed information on the various functional requirements. If possible this should include process diagrams and mock ups of files or material that gets used within the process. The more information regarding the process the better as this will give the developers the relevant information to understand the process and allow them to provide functionality that meets the requirements.
User Interface Mockups
A picture tells a thousand words
Providing a mock up of how the user interface should look provides a very clear definition of what the developer needs to create. The developer will not implicitly understand how the user will use the screen so the results may not be as user friendly as they could be. This is where the mock up comes into it's own.
- how the user will complete the screen,
- where will they go first,
- what is the most important information to gather,
- what are the mandatory fields required
A good screen design will make the implementation so much easier and the customer happier.
This area will generally be left to the developers and custom development to complete. However if there are specific technical requirements from the implementation then this is the place to state them. Good information here would be the environment into which the final solution will be deployed.
Are there specific requirements for the handling of data? Put this information here, one such example may be that no information is to ever be physically deleted from the database and should only be made inactive. Perhaps the system is to take data from another database and work with that....anything data goes here.
Non functional requirements are the soft touches that the system needs to cater for. Are there speed requirements for the system, what about issues with skinning, language, jargon?
Open Discussion Items
Openbravo is an open source project, and it is aimed that anybody in the community can expose his/her point of view. The points that need to be discussed will be exposed in this section and the achieved resolutions will appear in the next section.
Closed Discussion Items
Once one conflictive point has been discussed, the achieved resolution is presented into this point.
This is the template with all the points useful to cut & paste into your new functional specification pages:
== My Project - Functional Specifications == === Overview === ==== Purpose ==== ==== Scope ==== ==== References ==== === Design Considerations === ==== Assumptions ==== ==== Dependencies ==== ==== Constraints ==== === Glossary === === Functional Requirements === ==== User roles & profiles ==== ==== Business process definition ==== ==== User stories ==== ==== Functional requirements based on business processes ==== ==== User Interface Mockups ==== === Technical Requirements === === Non-Functional Requirements === === Open Discussion Items === === Closed Discussion Items === [[Category:Projects ERP]]