Why a developer should write his own documents and specifications (and bit more about documents in the area of R&D)
Why a developer should write his own documents and specifications (and bit more about documents in the area of R&D)
Why a developer should write his own documents and specifications (and bit more about documents in the area of R&D)
Reading time: 5 minutes
This subject is one of the evergreens in the area of RND. Despite that it is not exactly frequently discussed it is definitely one of the most present parts of the daily work of the SW engineer.
For so many years and projects I have seen quite a big number of situations, teams and projects. And there are different opinions on it. Still based on my experience I can say that the best approach is to request from each engineer to write his own documents and here I will present the points that lead to this firm conclusion.
First let’s explain why we need documents and when do we need them:
- Requirements from quality standards – due to the different variations of standards like ISO9001 and Automotive SPICE.
- Requirements from industry (e.g. automotive or consumer – for safety and other reasons) – in order for our product to comply and to be competitive we need the documentation
- Traceability of tasks completion – the design document for each SW component should reflect its internal state. So when we compare customer or internal requirements specifications to the design document – we can judge fast whether we cover all of them and how each one was implemented
- History of what was done and changed – many times design changes are done and some of them are definitely not easy to grasp without background knowledge. Having a history with short notes on the changes keeps track and eases future work.
- Explanation of complicated code in human language – despite the developer’s saying – “Read the source Luke” – the nerds and geniuses to pardon me – if I can read the why and what was done to result in this particular design and function separation – this spares time for me and any other colleagues in the future. Many times we don’t need the detailed comments in the header of each function and the inter-line comments from the source (that are mandatory nevertheless). Instead we care about the bigger picture with time diagrams, schematics and state machines. And those are not easily embedded into e.g. 10000 lines of source code. On top of that – some design decisions cannot be spotted easily from mere code reading for half an hour. So we need them described short and clear in a design document.
- Prerequisites for customer and maintenance manuals – if we have the information for how some particular component works – we can devise from it integration manual, final customer relevant features and ways of operation, design the proper way to develop a functional test and so on.
Most of the time the engineers are OK to write their own documents. However there is one not so negligible part of them that consider this a bit a loss of time. In addition many managers don’t understand why do we need those (and written good), and as a result they don’t plan enough time for this task. The consequences are rush, frustration and “not enough time to write it properly”. This is of course a problem of the management and each of us that have the technical background should give their best to explain to the higher level managers why documents need to be correct, exact, detailed and up to date. And we should put real efforts and demonstrate soft skills to persuade them when necessary.
But let’s concentrate on the point – why if I design a component – I and only I should write my documents. The reasons are as follows:
- If I can’t explain in a list of points what I have designed, written and done in the last X days – I lack the understanding of how my own code works and what I have done.
- To ask another person to write it – this means he should first spend time in understanding my work product and after this start to describe it.
Regarding requirement specifications:
Normally those are created from some human language specification – it doesn’t matter whether it comes from customer document, business analyst or business investigator. It may even come from your boss, who e.g. tells you – I need a device that does this and that. Now if we are in the area of consumer electronics we will definitely not create a detailed automotive specification. Nevertheless it will be good to have a list with all features in advance in order to plan our development. This document I call a requirement specification – even if it is a simple listing in a word document file, or one in a sheets table.
For the requirements in automotive sector we need a bit more. Those are the base for future tests for test department, and have specific characteristics described in this short article. Automotive requirements should not be written by person with little or no experience in the area. Why? Because he needs to understand in advance why we write them as explained in the article. Reviews here are mandatory (and only from experienced engineers, the newcomers should first be trained how to do this). But despite this if I have invested e.g. 2 weeks in writing specification and correcting all the points from reviews – I’m the person with the best knowledge on how to design the component. So – I should be the one writing it, and as explained above – I should be the one preparing the design document. My work should definitely be reviewed – this will help me perfect my product. But engaging other person with my tasks will only cost more money and time to the project.
Regarding test specifications:
It will be quite fast if I create it after I write my design document. A third-party review would always be good, preferably by senior co-worker. Another engineer may take care of the design of the test itself, and of updates and changes consequently, adding more tests, etc. But the initial version better be written by me. I will do it faster than anyone else. Especially when I have spared enough time to explain why, how and what happens inside my component.
Regarding manuals and HowTos:
A manual on how to use a component or tool can be prepared only by person with deep knowledge in the given area. Again a review of the document is preferable or enough times even mandatory (and the best would be if he or she is without experience with this subject). The review is like a test procedure performed by a separate person. This is important to prove that your manual really describes all necessary information and doesn’t miss points.
******* ******* ******* ******* ******* ******* *******
Good documentation results in multiple benefits for each project. The most important are:
- Time management – any future user of the given tool or component has all the digested information in advance. So he or she doesn’t spend time on investigating it on his own.
- The project management efficiency rises – each person knows that when he or she will switch task there will be information in advance and he will bother the responsible people after knowing the basics and only with serious questions. From psychological point of view – you will ask with background, and not simply asking for all possible basic details until you start understanding. You will be faster in your tasks. And a person that has invested the time to prepare the documents will not lose it 3 times to explain the same things over and over again to each newcomer. Not to mention that in the beginning, when a newcomer gets into the task – he needs to take a look periodically to his notes and when there are documents – in them as well. We can’t expect from anyone to learn a 10 pages complex specification by hard and understand it thoroughly from 2 passes over the document for an hour or two.
- Consequently the quality of the product will rise because we will have less loss of time in general. People will be forced to explain their work and will rely on the same from fellow colleagues. So all in the team will know that documenting is critically important and helps to the each colleague.
This culture of course needs to be supported by the managerial staff. It should be requested, explained and be part of any checklist for a task – have you updated the corresponding document, is the update reviewed (when it is significant)? If you, me or whoever hasn’t – the job is not done. Period.
******* ******* ******* ******* ******* ******* *******
Examples:
- Sensor driver design document – this was a component I have inherited in a very basic state of development, that I have expanded to double amount of functions and complexity, perfected, tested, written a test application for it and fixed all issues. I have worked on it and integrated it in 6 projects for over a year and a half. As I have become the senior sensor driver SW engineer and the team had 3 new junior sensor driver engineers at a certain point – each of them relied on the existing design document and Test Application HowTo in order to get into the projects and start doing their work for other projects. As I have created good document the junior developers approached me only with the really complicated issues.
- HowTo for data addition tools for Data Manager – for Kostal GmbH I have created this core component that was managing the data for 10 other components. It had complicated integration procedure on component update (also described in another HowTo). The engineers that worked with it were over 10. Each of them had to add data for their own component. Without a document I would have to add the data for each component myself. Instead they did it themselves and were forced to understand the usage in detail (only the usage, not the internal design). Short after finishing the project my contract with the company came to an end. I have written detailed design document and thus I was sure that the team will have the complete up-to-date information and will be able to integrate the component in any future projects. And they will be able to modify it easily thanks to the existing documentation. For the integration of changes several source generation tools were involved (some of them external by Vector GmbH) – so there was a HowTo also for this part.
- Requirement and design specification of Variant Manager. This was another task for Kostal GmbH. The project supported a line of devices with configurable options that resulted in the management of 20 features. After the end of my contract with them I understood that one of my ex colleagues had to do an update. I was absolutely sure that he will have no issue with the updates as again the specifications, comments and documents were all up-to-date, cleared of obsolete information and so on. Actually after some weeks we met with him and he confirmed it was an easy task thanks to the existing information.
- Test environment HowTo with notes on installation and tests creation. This was a task for how to setup and use the QT IDE and framework for writing C++ based functional tests. All crucial points on setup were explained, including with screenshots and notes on tests writing. Each time I (or few times also other colleagues) faced issues – I added more to the offline documents I have created and uploaded the updates to the online pages. Result – a team of 6 colleagues had all the information at hand. At some point in the future another 5 new SW engineers were added to the project and I was asked to do training for them. I had all the information in advance and it was easy for me to go back to the past and remember all beginners’ traps (thanks to the documents I have created). And it is clear that the same newcomers used those documents. When you have more than half a year passed from the given moment – you don’t remember more than half of the details by yourself. Having a roadmap increases the efficiency immensely.
- Requirements HowTo – with explanation on what is a requirement and how it should be written – for sentences, references, additional notes (info objects in DOORs). This is a short document I have prepared for the same project with the QT IDE, but it was in his second stage. The reason was that my team of freelancers had the task of full requirements review and edit. An article on this subject is available here. It explains what an automotive requirement is and despite that the explanations are short and quite straightforward – if you don’t have this simple knowledge in advance (even if you have automotive experience) – you may create literally useless specifications.
I hope I have presented my point good enough, even if you have no experience in the area. To conclude – when we go to an institution of some kind and have to fill e.g. 10 pages questionnaire – e.g. to register our company in the local administration – we always have examples. It is as well a kind of HowTo. So documents are not only helpful – in my experience those are crucial part of the work of an engineer and should be written with care, reviewed, updated and checked. All with one purpose – leading our work to a level of perfect quality and maximum efficiency of all processes.