Overview of Edsson best practice of software products engineering process for customers and new employees.

Times when customers just would tell developer what to do has gone.  Now we live not only between developers but also among business analysts and project managers. And each participant has its own role in the software development process.

We want to avoid any misunderstandings and misinterpretations of customer requests because it will cost us real money. That’s why we document all requirements.

Yes, of course, our customer can send us requirements in any suitable form, such as documents (long or short one), as website pages mockup, or as flow diagrams. Our business analyst will interpret those requirements into specifications which will tell developers and testers what to do, allow customers to check if everything is correct, will describe data models, web interfaces, use cases, and user interfaces. Our specifications are subject to change management. We will keep documents updated with any changes from customers.

How to read our specifications?

During years of productive work, we developed our internal standards for specifying all changes in documentation. We save all change history and developers can easily find what and where was changed.

When you will open any document, first what you will find will be lyrics (just trust me), such as title, the general purpose of this document, and so on. The main things usually start at ‘Data model’ chapter. 

Usually data models contain descriptions of tables, their attributes, and links. For better understanding and visualization, we draw data model (per module, of course) schemes in Visio. We draw tables with their attributes and relations. Here is an example:

Our rules to describe tables are next. Classes, attributes, and relations marked ▼ are system managed – means the User cannot set this value. Underlined attributes and relations are mandatory – means the User should input those data. Relations marked * prevent deletion of the linked entity. ∆ means value can only be set on creation. At the end of the table description, we can put any data constraints. This means, developers also should put those constraints into code after they will create tables. Here is an example – part (you can easily find differences) of one table ‘User Account’:

For our biggest project, developers made their own document with coding rules and standards. This will allow anybody (including new employees) to understand the written code and continue the project. Here is an example from this document - database naming conventions for tables and columns.

Next main chapter in all our specifications is ‘Use Cases’.  Or how the system should behave in this or that way. The good style of writing specifications means that every operation should be described through use cases: add new item, edit existing item, delete item. Also, all system actions should be described, for example, what if the system will get file. How to process new data? 

A good question, how to read and understand this table? Success Scenario – step by step rules for developers. This means what the system will do in a successful situation. But what if the User will input the wrong value in a text field? This means system will get wrong value. All possible ‘what if’ situations should be described in Extensions. We always try to explain every step as clear as possible. Our aim is that not only developers should understand what is going on, but customers too.

And the last main part in specifications is User Interface or simply ‘UI’.

We design prototypes of used forms. Of course, real developed form will not be exactly the same. Our design allow the developer to understand which text labels and input fields should be used. How to arrange all fields on form, how to align fields, if any field should be marked as mandatory or not, what buttons should be developed for this form and where those buttons should be situated. Usually under-designed prototype, we describe which use cases should be USED by pressing button (or by any other possible action). Also, we describe constraints for input data.

Good style of specification writing means that almost all system reactions will be described in use cases, not under the designed prototype or data grids.

In ‘UI’ part we describe which data should be displayed on pages in grids. Which actions can be done on those data. Here is an example – Role Page: Page contains List of Roles with filter row.

For many projects the DevExpress controls (http://www.devexpress.com/) are taken as standard of user interface design.

Of course, sometimes we add more parts into specifications. If system should send and get data, let say, in xml format, we will describe web intrfaces: request and response with all fields and their types inside. (Well, for other format, such as json, we also will do the same work.)

If system should be used by Users with different permissions, we will describe permissions as separate chapter in one document. And than, will put links from other specifications of this project to the document. We will not describe twice the same information. Yeah, this is one more rule for writing specifications.

The next step is testing according to specifications. Based on initial requirements our testers will write test plans. The plan will describe which scenario will be tested and how, including scenario steps with expected results, which initial data is required to execute the described scenario. Testers will define if the plan is subject of manual testing or requirements of automated test. Here is an example – view of one of our test plans:

To assume everything written above, all our specifications and test plans are subjects of change management. What does it mean? It means that every change or bug should be registered in our bugtracking system. Years of productive work tell us, it’s easy and really handy for all team members. No more questions “why?” and “who has done this?”, all update history is logged. Here is an example – part of our bugtracking system. Changes and bugs (marked with red ladybird) with their descriptions, statuses, phases and users who now is responsible for the topic.

And, of course, business analyst will update specifications with those changes. BA will create new version of existing specification, will put tracking numbers near changes and will update history.  The same will do testers with test plans. Our test plans always correspond to current versions of specifications. Here is an example – view of specification document with new changes, numbers are marked yellow.

Developers will update the code. Testers will execute tests and close tasks in bugtracking system. The project manager or business analyst will prepare notes for release with included changes. Here is an example – part of release notes.