From spec to design of a business application¶

• Table of contents
• From spec to design of a business application
  • Documentation in the traditional approach
  • Documentation in the agile approach
    • Examples of themes, initiatives and epics
    • Examples of user stories

This page will describe

• what processes we can follow to arrive at detailed software design from layman specs, and
• what documents we need to create along the way

We will first start by taking a look at the spec and design documents conventionally used in the industry for a few decades, then look at the terminology used by the much more recent agile development chaps, and then arrive at the documentation we need for our use in Merce. After that, we will describe the process we can follow to arrive at the detailed design document.

The objective of this entire process is to arrive at documentation which can be handed over to a bunch of good programmers who can then do the coding and testing without discussing spec with the client.

Documentation in the traditional approach¶

The traditional approach, called the "waterfall" approach, believed in documenting everything in great detail, getting the client to sign off on each document, and then starting software development. In that approach, the steps were as follows:

• The BA (Business Analyst) studies the business operations of the client, suggests some changes to the process for suitable computerisation, and then captures all this in something called a BRD (Business Requirements Document). The BRD is also known as BRS (Business Requirements Specifications), FRS (Functional Requirements Specification), etc. They roughly mean the same thing.
• The tech team then sits with the BRD and creates the SDD (Software Design Document). This contains technical design and architecture which is useful for the programmers who will develop the software.
• Modern applications are expected to have very good UX and UI, since no user wants to go through a training programme or read a user manual to use it. Therefore, a third activity is the UX and UI design, which is done by studying the BRD. This UI design is used by developers to design the screens.

This is three-part process for software design and specification in the conventional approach. The dev team finally gets

• the SSD
• the UI spec and screens

to do their coding.

Documentation in the agile approach¶

The agile approach does not believe in creating documentation first, and then starting their coding activity. They believe that documentation needs to be created in short chunks, enough to feed the dev team for 1-2 sprints. They have a very specific structure for their software spec. They talk of specifications in a 4-level hierarchy:

• The theme: a company-wide focus area, specified in broad terms
• The initiative: a large objective or target, assigned to a department or multiple departments, to achieve in a time-bound manner. Many initiatives may emerge from a theme.
• The epic: a target to be achieved by a single team. Many epics may emerge from a single initiative.
• The user story: a small, single deliverable, demo-able task or function or feature to be implemented in a software application. Many user stories together are used to deliver an epic.

Examples of themes, initiatives and epics¶

• A theme could be: "we need to increase our profits by 20% in the next financial year."
• Some initiatives which may emerge from this theme:
  • Initiative 1: cut costs by 10% in the fixed overheads of the company
  • Initiative 2: improve programmer productivity by 5% through all teams
  • Initiative 3: acquire 15 new customers in the next financial year
• Some epics which may be triggered by the Initiative 3 (acquire 15 new customers):
  • Epic 1: recruit and train 3 new sales executives and deploy them on the field
  • Epic 2: revamp the website to reflect more attractive offerings we have
  • Epic 3: set up a call centre for outbound sales calls for lead generation
  • Epic 4: deploy the latest version of a salesforce automation system and train the full sales team on it
• Some epics which may be triggered by Initiative 1 (cut fixed costs):
  • Epic 5: explore relocation of HO to less expensive real estate
  • Epic 6: install intelligent AC monitoring systems to reduce AC electricity bills
  • Epic 7: downsize some of the clerical departments and outsource to a BPO

As is evident, the agile approach to specifying a "project" is not limited to software development alone, and works very well both for software and for non-software projects.

The examples clearly show:

• A theme is a company-wide focus area, stretching over a longer term. It is implemented by kicking off various initiatives in the company.
• An initiative is a large activity with a single target or objective, but may involve multiple departments, functions or teams
• An epic is a smaller activity which involves exactly one team within one department, and it is expected to be completed in a shorter timeframe than a theme or initiative. The epic is what we, in the software world, call "a project".

We can almost characterise these things this way:

Examples of user stories¶

Here we are assuming that we are building an FA system.

• As an accounts executive, I should be able to enter new vouchers into the system so that I can log all accounts transactions.
• As an accounts executive, I should be able to edit existing vouchers so that I can correct errors in them.
• As an accounts manager, I should be able to see a list of vouchers entered into the system in the last day or week, so that I can monitor progress of work and keep track of recent transactions.
• As a Financial Controller, I should be able to see the up-to-date P&L statement, so that I can keep track of overall company income and expenditure.

Every user story has the following parts:

• Persona: e.g. an accounts executive
• Desired feature or capability: e.g. see a list of vouchers entered into the system
• So that: e.g. I can keep track of progress of work and see recent transactions

User stories, in the context of software development have the following features:

• They are the smallest unit of software spec or feature which can be delivered and demonstrated to the end-user
• They always specify something which the non-technical end-user can use, therefore they will never specify just a library to be developed or a database table to be created
• They are almost always something which can be implemented by a small dev team (a sprint team) in a few days at max.

As a result of all this, they are almost always full-stack. In other words, implementing a user story involves building the screens (HTML, CSS, etc), writing the front-end code (browser-based or app code), writing back-end server-side web service calls, etc, creating database tables, integrating with other systems as needed, and so on. Each user story may be a very narrow feature or function horizontally, but is full-stack vertically.