Before you can build something that something has to be defined. Every detail has to be decided at some point. Because of the difficulty of communication between individuals and the difficulties that are inherently involved in complex systems we recommend various practices.
While these techniques are used for some components in the core Open For Business functionality they are primarily meant for those who are creating derivative works based on OFBiz. The reason for this is that OFBiz is a generic framework, set of application components and suite of applications. In many cases these applications can be used as is but they are not meant to be everything to everyone. Because of this work will likely be needed for derivative works that are targeted at a specific industry, type of business, or specific end user.
Methodology: Keep it simple, but not too simple
There are dozens of different software development methodologies, and more are being introducted all the time. There are lots of good ideas presented in the hundreds, or even thousands, of documents available about different methodologies. In general we recommend the "agile" approach, but that needs to be qualified given the different perspectives that have been attached to that name. In general we recommend keeping it as simple as possible, but not too simple. For more specifics on agile software development see the Agile Alliance web site.
So the big question is generally: what is the minimum that we need to handle this project? The more methodology you have the more time and money you will spend on it. The less methodology you have the greater the chance that the requirements of the project will not be satisfied.
There are really only two roles necessary for any project: a buyer and a seller. In the case of software projects, and other service offerings, the more common terms are customer and developer. Those are the terms that will be used in this document. The term developer is used loosely here and refers to anyone that produces actual deliverables. The term customer is also used loosely here and refers to anyone that specifies what will be done and pays for it to be done. In some cases the customer and developer will be the same person, or the same group of people.
It should be noted here that an important part of the "customer" role is the actual target user(s) of the software. If possible reviewing stories and use cases (as described below) with users should be done. Interviewing those who are currently performing tasks that will in the future involve interaction with the new system can make it much easier to acheive complete and effective results. This is true on many levels. For instance, the best usability can be acheived by reviewing screen/page prototypes with real users and then validating final deliverables with real users. If the user group is large this may require a lot of work to get a good sampling of the different users of the system.
In many projects the two roles, customer and developer, will consist of groups of people and other roles will be introduced within the groups to clarify responsibilities. In these cases the methodology may also have to be more significant to keep things from deteriorating into chaos.
One practice that can reduce the need for a complicated and detailed methodology is to have one person from each group act as the agent for the entire group. Of course, that agent should discuss things with the rest of the group, but if the number of voices for interaction between the groups can be consolidated to one then communication and management of details will be much easier.
Note that for large projects having one agent for each side will not be practical. In those cases dividing the scope of the project and likewise dividing the customer and developer groups will be necessary.
Another variation on this is where a group creates a product targeted at hundreds or thousands of customers. In this case the "customer" that defines the product will be part of the same organization that produces the product. Given the definition of customer above the sales, marketing, and testing groups should be in the customer group, and an agent from that combined group should coordinate with the development group.
The biggest trick with communication is to find the balance between to much and too little communication. The burden for this is generally on the customer because it is customer that specifies what will be build. Like I said at the beginning of this section everything that will be built MUST be defined sooner or later. Anything that is not specified by the customer can be handled in one of two ways. The developer can decide what will fit into the gaps or the developer can request clarification and details from the customer.
To facilitate communication and make sure that the final result satisfies the needs requested by the customer the following process is recommended.
One important aspect of this process is that it should be repeated frequently and the scope for each pass should be kept small so that when miscommunications occur they can be identified and resolved quickly.
While this process is simple and involves simple roles and artifacts it can be used as a skeleton for a much larger and more detailed process. Each step can be divided into many steps and extra steps to compensate for the needs of a specific project can be added.
Also note that this general process is the basis of the Work Effort components that are part of OFBiz and those tools, as well as many other available tools, can be used to make artifacts and other information easier to manage.
- The customer requests features by telling a "story" about each feature desired.
- The developer creates one or more requirements for each story by writing a more formal "use case" describing in detail how the resulting component(s) will be used.
- The customer reviews the use case(s) and provides feedback to the developer if necessary. If feedback is returned the developer adjusts the use case(s) and resubmits them to the customer. When the customer is satisfied the requirement is approved for implementation.
- The developer defines tasks that must be done to create or modify components in order to satisfy the approved requirements. At this point, if desired, time and/or cost estimates should be associated with the tasks.
- The customer can specify priorities on the request, requirement or task level. Given that tasks may have dependencies the actual order may be changed by the developer such that prerequisites are satisfied first.
- The developer does the work described in each and demonstrates the result to the customer. To improve developer productivity interruptions during this time should be minimized, except of course interruptions related to changes in what is to be done for that component. The actual time and/or cost should be recorded at this point if desired.
- The customer reviews the deliverable and either approves the work or requests adjustments as needed in the story, use case, and/or tasks. Making adjustments at this point involves going back to previous steps and then the same subsequent steps should be followed to complete the process.
You will notice that this process involves a great deal of customer interaction. If done right the customer and developer will interact on nearly a daily basis. For coordination and management periodic meetings should be held to review new requests or changes to existing requests and to adjust priorities as necessary. These meeting should be held once every one or two weeks for most projects.
After looking at this list you may have questions about what constitutes a story, use case, and task.
A story is essentially an informal free form document from the customer that describes what is desired in complete sentences or as an outline. Precise details are not needed at this stage. Note that this document may change to be more precise or to include additional aspects. This document will be used to create more formal use case(s).
A use case is a document that contains detailed information in a more formal structure and represents the complete specification corresponding to one or more stories. A use case should include the following:
- The primary and other actors, defined by the roles of the the users or systems that will be interacting with the functionality
- The goal(s) of each actor and/or the overall interaction
- Usage scenario(s)
- The primary actor
- The goal of the scenario
- Conditions that trigger the scenario
- The result(s), includes both success and failure results
- Scenario variations
- Errors, exceptions, and resulting actions
Note that for simplicity scenarios should be kept small and include only the minimal basic process. Variations on process should be defined separately. Exceptions and errors in the process should be defined separately along with their results.
Defining tasks is generally fairly simple and should be done by the developer in a form and using terms that the developer will understand. There is a lot of meta-data that is generally associated with such a task. Examples include estimated and actual time and cost, start and end dates, all parties performing or otherwise involved with the task, and so on.
Some basic preparations should always be done before getting into the implementation. Some basic principles and a basic process has been presented. Because of the nature of how most projects work all of the steps in the process will be done in one way or another. Following this process does not require the creation of any written documents, although in many cases that will help quite a lot. It can be done through verbal conversation, or even a series of thoughts inside one's head.
The process described is meant to be customized to your needs. Following it as is should do for most medium sized projects. When there is only one or two individuals involved, or tens or hundreds of individuals, changes will obviously be desired. When modifying the process keep in mind the basic principles presented and be especially careful about leaving out communication steps, espcially the communication verification steps.