Why Software Design Documentation? How To Write a Good Software Design Documentation (Part 2)

In the part 1 of this article, I discussed about what is required in making a good design documentation, now in this part 2, we will talk about the style of documentation writing. Relax your mind and be open minded because it is quite different from the secondary school English class that we all attended.

| Want to start an eBusiness and Grow it Globally with free IT, Legal, Internet Discounts,3 Months SME Startup Course, ePayment Integration, Biz Development Services, Free Website, Free SMS Units/Portal all done for you within 30 Days?

Start Here>> Click  >>> Start a Digital Business in Nigeria

                   HOW DO WE WRITE A DESIGN DOCUMENTATION?

When thinking about what to write in your design documentation, always have in mind the following checklists.

1. Write as simple as possible as you can

Don’t write like scholars when writing documentation because you are writing about a solution and problem that your project is solving. Write as concise and precise as possible.

1. Use simple words
2. Use short sentences
3. Bulleted list or ordered list is okay
4. Use user storyline e.g “Canteens connect with chefs and exchange contact using qr code”
5. Use Charts and Diagrams Plenty

Many people says that pictures speaks thousands and nothing is self-explanatory like images (infograph).

Charts and diagrams are useful when comparing potential options than texts. Google Drawing is a good tool for creating diagrams that wows the eyes and connects the brain to the information passing.

Just always remember to add a link to the diagram using screenshot, so that it will be easier to update it later.

3. Never Omit Numbers

Always use numbers when explaining things/parts that needs quantity and quality. It makes it easier for the reviewers and readers to picture the values easily

4. Always Pick Funny Words

See your documentation as your canvas where you can draw anything that you like and people will appreciate it well.

5. Always Do skeptic Test before sending

Don’t be in hurray to send your design doc without proofreading and testing extensively.

It is even advisable to give to someone else to go through it for and make corrections if possible.

Sending bugging design docs can be devastating and image tarnishing as well.

Don’t hit the road unbalanced and engine checked.

6. What happens if I am not available

Yes, let say that you are sick or on vacation and there was no internet access. Please, can anybody update the documentation that you wrote? If it is not possible, then you need to revisit that documentation again and make it easier for people to co-work on it for you.

THE PROCESS NEEDED AROUND THE DOCUMENTATION

Design docs make it easier for you to receive feedback from the managers before wasting a lot of time implementing the wrong solution or proffering solution to the wrong problem.

The process of making awesome feedback mechanism to get specific requirements that you will need in your projects are explained below.

It is compulsory that every people working on the project must be part of the design process as a team even if it is the tech lead taking decisive decisions but all the people must involve in the discussion and add something into the design process.

Secondly, it is even good to make a prototype of the potential solutions by showing it to the team than just doing any funny whiteboard idea sharing.

Note, that doesn’t mean that the production code as started but just to show how the solution will pan out.

It is good to use a hacky previous code to validate the ideas that you wanted to pitch over to the team.

Since you have gotten the house into ransom, then you can now do the following things accordingly

1. Ask the experienced engineers in the team to review what you have tabled. This will make it easier for you to get a first-hand picture of what they wanted in the project.
2. Don’t go into the conference room with a whiteboard because you will surely need one
3. Take a deep breath and explain the “solution” that you are using to tackle the “problem”
4. Take the team through the process of implementing the solution you have in mind and try to convince them why it is the right solution

A good design doc is successful if only the work is done successfully as well. A good doc must contain the following as a recap on the discussion:

1. Always spend much time on gathering resources and requirements needed for your documentation design
2. Always listen to the reviewers when given update on their fin dings
3. Let them know that you are using solution ‘x’ to de-risk problem ‘y’
4. If the solution is not attainable, let them know as soonest as possible.

Please leave your comments if you have any feedbacks

| Want to start an eBusiness and Grow it Globally with free IT, Legal, Internet Discounts,3 Months SME Startup Course, ePayment Integration, Biz Development Services, Free Website, Free SMS Units/Portal all done for you within 30 Days?

Start Here>> Click  >>> Start a Digital Business in Nigeria