Software development process is fast catching up with agile, but old minds with their set perceptions are still sitting on top of organizations and they hate change. For them software development is still waterfall. They still try to fit in old apparatus in the new lab – doing agile the waterfall way. Result – multiple hybrid agile models all across the software service industry.
The advent of agile requires them to throw away the concepts of creating piles of documentation that just helped in adding ‘weight’ to the delivery. A very stereotyped It-needs-to-look-bulky-to-look-expensive mindset. They still do that with software, they do that with processes and they do that with documentation. I’ve already been talking about rubbing off features from your product canvas in previous articles. I will perhaps feel disgusted enough and write about leaner processes in detail some day. This time I am trying to focus on creating documents the new way – the agile way. And that means wiping off all templates, bulky documentation processes and focusing on the need of it. And I am not going to save digital paper by keeping the page count low. I am talking about creating presentable, readable, useful software documents that are easy to create and maintain.
Cover page – It makes the document look presentable, authentic and interesting – if you make it properly.
Table of contents – As a creator it may seem simply useless but as a reader it is very useful specially for larger docs so one can directly reach the point of interest.
Document history – Keep it simple. Just make a simple table with date, author/reviewer, modification done.
Main Contents - For any software related document here are some important labels you should keep in mind. You can select and add the most relevant ones.
1. Objective – Over all objective of the product. Even if it is not your own product you should try to know what is the aim of creating this new piece of code.
2. Target users – Everyone is never an answer. Please try to look for specific age groups, region, religion, gender bias or other demographic parameter. It is extremely important to narrow down the target users as much as possible.
3. Competitive Products – It seldom happens that there are no similar products. One should analyse and jot down the feature highlights of other similar products.
4. Non-Functional features – Before your target readers get engrossed in the overwhelming list of features and functionality, discuss a few desired features like performance, security, scalability, internationalization, orientation(in case of mobile apps).
5. Scope – Again, while the suspense of feature list builds on it is good to tell the readers what is in scope and what is not. The entire feature list would obviously be in scope but there may be corners here and there that you may want to keep out of scope.
6. Feature list – It is always good to pour out how you ‘see’ it. A functional wireframe (simplest of sketch if also fine) with a simple explanation of what control does what or takes users to ‘X’ screen or allows user to do ‘L’ thing. One may not require to keep adding little validations, checks etc. That should rather go in coding guidelines/checklist and developer should be expected to take care of such ‘regular’ stuff.
7. Designs – It is also good to start with a little showcase of colors and themes you find apt for the product (based on use and target audience). Based on the timelines one has – she can add few finalized screens.
References – May not be relevant for requirement or estimation type documents but it is good to add the apps/websites/books/documents you found useful as references at the end.
Templates v/s Checklists
What we need is checklists (like the one above) and not templates. With templates comes fear/lethargy of maintaining the status-quo. If every document is different – it should look different and focus on solving the problem instead of maintaining the so called standard format. Auditors and Managers want to you to stick to their ‘prescribed’ formats because it is easy for ‘them’ to monitor and review. But that’s not what docs are for.
The sample I’ve attached is to understand the concept and see it in action not to be used as a template. Feel free to add/ edit/ remove the sections to make it more relevant.