Writing requirements: assembly manual or design manual? Don't do both, it just confuses me.

Requirements should be written two different ways. Of course, some people try to get away with not writing them at all. And some people try to write them both ways at the same time. But, let's focus.
You can write requirements for project management completion or business process value creation. This is the difference between an assembly manual and a design manual. Just because you can build a soap box derby car doesn't mean you know how the brake works let alone how to make a better one.

My main complaint these days is that projects manage "requirements" but are really just collecting expectations users have. Here's a few random wants, needs, or expectations, but not requirements.

• Joey wants parts that optimize speed like Z-glas wheels.
• Phil likes rear ballast weights for steering control and speed. The result of the combination of the wheels and weights is not known.
• Mom is worried the brakes could fail. 
• Dad wants to make sure we win at least one race. 

Now go build that.

Soap box derby management

Agile project management styles promote project requirement writing in user stories. The stories remind us of what people want. Joey's story says "As a racer, I want to go really fast so that I can become the state champ." To translate that into something useful, projects need a map of activities and tasks to organize the moving parts so the stories provide useful input:

• Car assembly (activity)
• Put fast wheels on the body spindles (Joey).
• Stabilize steering with weights in rear of the body (Phil).

The other stories get put somewhere and maybe in a new category. Nobody has a standard process. Nobody really defines them well. Somebody will likely want to have the wheels in the shape of a kitten, etc.

Programmers and especially software testers want scenarios that describe the process well. They abstract out the system and sub-systems and provide details in a use case that describe the steps of the process.

You can't assemble a car from a use case diagram but you can test it after you figure out what the design should be. And you see that the brake system is probably separate from the steering system. And you know how to add to the functions if you want.

Both types of requirements should be done so that the project is implemented successfully and the operation of that process continues to show good results. But with pressure to deliver quickly, the project style is always a bright light that management moths are attracted to. The old-school requirements document that instructed the software developers how to organize and build the software has become more and more the responsibility of the software developer due to increasing complexity.

Project requirements

From the project schedules in a Gantt or PERT format to the process maps today, we still just want to keep our work progress under control. Requirements prepared for project management include:

• chunks of project activity ordered by completion time and priority
• associated documents with that chunk that help to create it
• and are in the context of project building only

The target audience of these requirements are the project managers those interested in project progress. So the document creators will write these documents to provide 

• good metrics and
• progress summaries

In an Agile project, elicitation happens at the user level with the stakeholders providing their user stories from their point of view. The user story is a marker for the project manager to take care of their request and for more conversation later when appropriate. The user provides the priority and the value as they see it.  The user story provides the raw materials for the chunks of project activities and tasks (or goals and journeys) that are then mapped to show project progress.

Because there's no real unit for measuring the scope of the sticky note task for what to do, the application of different names and styles are not easily understood. Sometimes there's a goal that seems like a higher level activity but it could be a feature. Maybe there's a theme but that could be just a descriptor to group various chunks. Even user stories are re-purposed to a minimal viable sentence style to fit on a sticky note that just look like a smaller activity.

The mapping style process that generates hundreds of sticky notes is not mapping a project as much as it's trying to outline the entire process for development. It looks impressive but misses the goal of providing good metrics and summaries and documenting too many of the details. Mapping should be about understanding how to deliver simple and important features so you get feedback quickly. Remember the Agile principles! Here I agree with Mike Cohn's point about the story as a conversation point.

Projects are about people that get stuff done. Short-term successes of project oriented requirements documentation can be measured by

• end products for completing one or a group of chunks
• satisfying the person the activity was elicited from

At the end of the project, you take a breath, see if you did a good job, and then go on to the next project. Goals for project requirements are to

• complete the project under budget and on-time
• minimize risk during implementation

Process requirements

Requirements for software development or any process decomposition that seeks to uncover better value involves

• chunks of process descriptions ordered by size and trigger
• descriptions of data, rules, and process qualities
• context of system's SLA, other systems, and management systems

Here the target audience for the requirements are the developers or implementers of the process. Notes about how the system might print a report or the way that it should work with other systems are useful. The documentation provides a high level of

• communication and
• understanding as a result

In a more traditional project, the elicitation starts at the user level with the stakeholders providing what they expect from their point of view. That's not too much different from the Agile style.  User expectations are collected through workshops, interviews, and document inspection. Analysts create testable requirement statements from these.

What should happen next is that the project should be decomposed by use case processes to provide visibility to the business for what processes are requested and how they function. Often this is skipped and the code and its class diagrams provide enough functional visibility to technical people because of excellent tools. The unfortunate result of passing the buck here is to let the technical staff make business decisions. This also removes quick decision making from the management because it's been encased in code.

At the end of the requirements structuring, you can test whether you have done a decent job or not. Short-term successes of process requirements are measured by

• verifying all requirements are testable
• grouping process chunks to the same granularity
• having one chunk size end with business value being realized
• separating functional from non-functional requirement types

When you complete the development process, you end up with a product you hope will last for many years through many changes. Goals for process requirements are to maximize

• adaptation to change through structures with low coupling and high cohesion
• realized business value

Combinations

If you try to merge the two types of documents or skip either one, you'll end up creating less quality in your software and less value in your results. The purposes of each type of document should be clear. Project documents tell you when and how much you can build at one time. Process documents tell you where the value is and let you understand how to manage the automated decisions.

Keep the roles and documents focused so you don't confuse me. If you need to, the process document can be split up into project friendly pieces so it can be used like a work breakdown structure. I'm of the belief that a goal-driven use case is equivalent to a work package myself. Arrange pieces into iterations with IDs from the use cases based on priority and size or complexity. Track the user stories back to the functional or non-functional pieces.

If you want to win a soap box derby, ask what the requirements are. Then build your process documents to deliver that value from the high level on down to the design level if you need it. The last step is to build your project document to get your soap box car out the door. Now, go win that race.