Edsson Software Product Engineering Process

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

Times when customer 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 software development process.

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

Yes, of course, our customer can send us requirements in any suitable form, as document (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 model, web interfaces, use cases and user interface. Our specifications are subject of 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, general purpose of this document and so on. Main things usually starts at ‘Data model’ chapter. 

Usually data model contain description 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 User cannot set this value. Underlined attributes and relations are mandatory – means User should input those data. Relations marked * prevent deletion of linked entity. ∆ means value can only be set on creation. At the end of table description, we can put any data constraints. This mean, 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) understand written code and continue 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 system should behave in this or that way. The good style of writing specifications means that every operations 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 system will get file. How to process new data? Here is an example – operation of locking user account:

The good question, how to read and understand this table? Success Scenario – step by step rules for developers. Means what system will do in successful situation. But what if User will input wrong value in 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 prototype of used forms. Of course, real developed form will not be exactly the same. Our design allow 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 mark 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. Plan will describe which scenario will be tested and how, including scenario steps with expected results, which initial data is required to execute described scenario. Testers will define if plan is subject of manual testing or requirements of automated test. Here is an example – view of one our test plan:

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. 

As the next step project manager or business analyst will include those changes to release planning. 

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 code. Testers will execute tests and close tasks in bugtracking system. Project manager or business analyst will prepare notes for release with included changes. Here is an example – part of release notes.

Customer is happy with new release!