Raging Gazebo’s Software Engineering Plan for Small Teams

However, without a written plan a small team of software engineers and developers may find themselves clashing over ideas, designs and goals. Team members’ morale will quickly diminish as they find developed designs being deleted because of misunderstood objectives or duplicated code developed by another team member. Production burnout will occur as team members are taken away from their families to work overtime to meet agreed upon deadlines. If there are publishers or customers involved, the lack of organization can be viewed as incompetence and the loss of customers’ confidence can be very costly for business. Without a plan, budgets may inflate and deadlines may slip. So software engineers must do at least some planning.

For small or large teams that may have changing and flexible requirements (such as a video game or a simulation model of a yet to be completely defined system), the answer is not a big restricting software requirements specification (SRS) and/or a strict Big Design Up Front (BDUF), but rather a small agreement between the software engineers and the customer (systems engineering, management, publishers, etc) and then a small design created from that agreement. From this little bit of planning software developers can develop a small product or prototype. The engineers can present that small product to the customer to evaluate and derive desired additions and/or changes to the product. The engineers will build another small plan and the developers using the plan can build upon the small product. In an iterative fashion the customer will re-evaluate the product, come up with additional desired changes to the product; and the cycle continues until the customer is satisfied with the product.

This iterative approach is good for small teams that cannot spend the time and/or resources on a huge SRS and BDUF, as suggested by the waterfall method – especially if the customer wants to see what the software engineering team can do in a short time.

To begin, the software engineers must collect from the customer their objectives for the product and of the product. In sorts the team is interviewing the customer to capture the customer’s vision of the product and how they intend to use the product.

The process of capturing objectives from the customer can be informal over a beer at the bar or formal in the office in a cooperate meeting, it can be a set of emails or a presentation. Whatever the method, this is the time the engineering team will allow the customer to layout their desires for the product uninterrupted. The team will record everything the customer iterates. The customer can go into as much detail with their desires; or they can keep it brief “I’d like a coffee maker that automatically brews at a set time in the morning”. The idea is to allow them to express their objectives freely. However, the engineering team must be careful not to commit to anything until they are allowed to analyze the objectives and sort them out into requirements on paper (soft and/or hard).

After collecting the objectives from the customer it is time for the software engineers to start drafting high level software requirements called Customer Requirements.  These set of requirements are requirements of the product and the production of the product that is agreed upon by all stakeholders (the team of software engineers and/or the customers, publishers, system engineering, etc).

Traditionally, customer requirements are broken up into two production phases, pre-production and production.  Pre-production phase’s requirements define the foundation of the product and describes the starting point of production.  Production phase’s requirements define additional desires and changes to the product after the foundation of the product has been completed.  In an agile approach these two sets of requirements do not need to be completely defined before development of the product begins.  However, emphasis to have a good understanding of the pre-production requirements is desired before development begins, so a well developed prototype can be produced for evaluation by the stakeholders.

In RG’s small team plan there are still the traditionally defined production phases, but the phases contain categories of customer requirements.  In the pre-production phase there are the production and prototype requirements; and in the production phase there are the primary and secondary requirements.  The production requirements define how the product will be produced such as milestones, tools, rewards, etc.  While the prototype requirements are the bare minimum set of requirements in order to produce an interactive product that all stakeholders can evaluate.  If there is one requirement that is incomplete out of the prototype requirements then an interactive product cannot be produced.

For example a set of prototype requirements for a coffee maker:
1. The coffee maker shall have a hot plate.
2. The coffee maker shall have a pot.
3. The coffee maker shall have a filter.

With the three requirements outlined above the stakeholders can make a cup of coffee with a developed prototype from the requirements.  If any one of these requirements are missing then the stakeholders cannot make a pot of coffee nor a prototype.  The plastic housing, the funnel used to pour the coffee, the filter casing, etc are all “extra parts” of the coffee maker that is used to enhance the experience of brewing the coffee easier.  These “extra parts” are outlined within the production phase.

The production phase primary set of requirements outline the most desired set of requirements that must be completed to satisfy the customer.  While, the secondary set of requirements outline the desired set of features the customer would like to have in the product, if there is time and the budget to implement those features.

The software engineers will take the objectives captured from the customer and write the requirement categories outlined above in shall statements.  The engineers will pay close attention to the pre-production requirements while only lightly drafting the production requirements for the first iteration of the customer’s SRS.  The engineers will assume and fill in oversights where necessary to make sure the prototype section of pre-production requirements can lead software development into producing a prototype.

After, the engineers has completed the pre-production requirements the now drafted SRS is returned to the customer for their approval.  The engineers must emphasis to the customer that the SRS is not final and can be changed by any of the stakeholders, but must be agreed upon by all stakeholders before the changes are accepted.  At that point the engineers will work with the customer to clarify the pre-production requirements in particular the prototype requirements.  After all the stakeholders agree the prototype requirements “looks good” then the software engineers will take the SRS back and start drafting the derived (pre-production) Product Requirements.

Product Requirements are requirements derived from the customer requirements that are used to define the components of the product.  Although, it is encouraged for the customer to view the product requirements, the requirements do not need the customer’s approval.

The objective of product requirements is to define product’s components that will need to be developed.  However, the engineers must be careful not to design the product through the requirements.  Well written product requirements will cause a design to fall out of requirements.  All requirements detail what a product is (aka “the what”) and a good design will detail how the product will work (aka “the how”).

An example set of prototype customer requirements and their derived prototype product requirements:
1. The coffee maker shall have a hot plate.
a) The hot plate shall have a power cord.
b) The hot plate shall have a heat conductor.
2. The coffee maker shall have a pot.
a) The pot shall be made of Pyrex glass.
b) The pot shall have a handle.
3. The coffee maker shall have a filter.
a) The filter shall be able hold a cup of coffee grains.
b) The filter shall allow liquid (water) to pass.

Traditionally, at this point there can be a third set of requirements that is derived from the product requirements called Functional Requirements or Feature Requirements.  Unless the customer requests the engineering team to produce an SRS at this level then it is discourage.  Statements like “The menu buttons shall be green from the drop down menu.” will be handled, through the design of the software, through the developer’s choice when developing the related task, or through the iterative process where the customer requests the menu buttons to be green.

Once the prototype’s product requirements has been established then the software engineers working with software development will produce a draft design of the prototype.  From this design tasks will be drafted and assign.  These tasks must point to at least one product requirement, but can also point to multiple product requirements, if necessary.

If there is a task that cannot be linked to a product requirement then there is a missing product requirement that software engineering will need to write.  If there is a missing customer requirement that a product requirement cannot be linked with then there is an oversight that all stakeholders will need to look at.  However, this should not stop work on the task, unless the customer does not approve the customer requirement; then the developer can shelf (or roll back) any associate work performed on the task.

Tasks must be defined in such a way that it will take less than a man week (five eight hour days) –  preferably a few days to complete.  In a few extreme cases two man weeks are okay.  However, if a task is estimated to be larger than the given time frame then the set of tasks (or the requirements) are poorly written and needs to be re-analyzed and broken up further.  Also, be careful not to have a huge set of “less than a day” worth of work.  Although, it is fine to have a hand-full of these tasks.  Something is wrong if all or most of the tasks are written to this detail.  If tasks are written to this detail then engineering and the developers are spending to much time and detail in the design.  These details will be quickly flushed out in either development or through the iterative process with the customer.

Once the prototype’s tasks are implemented then the prototype is tested against the product and customer requirements and then presented to the customer by the engineering team.  The customer will evaluate the prototype and if need be, working with the engineers revise the prototype’s requirements; and the chain events occur again.  However, if the customer likes the prototype then the engineers, working with the customer will move onto and complete the primary customer requirements; and as with the prototype’s requirements and development, the process starts over again.

Now with the pre-production phase defined and the prototype requirements and development completed.  The software as well as the requirements can be released to the customer for evaluation iteratively as the software evolves.  Traditionally, an iterative release may occur every two weeks.  However, there is no strict rule how long an iteration can occur.  The recommendation is no more than a month.