I am somewhat late to the party but I have recently finished reading 'Inspired: How to Create Tech Products Customers Love' published in 2018 by Marty Cagan from the Silicon Valley Product Group. It's a fantastic read.
The book was very enlightening and I would highly recommend it to any fellow software engineer in understanding their role in an aspiring product led environment. The language is casual and the content is delivered in short concise chapters, with welcome interjections of high profile product use cases. On this point however, it may have been worth balancing out these successful use cases with some product efforts which for one reason or another went sideways, provided there was a teaching moment in there. We often learn more from the failures than the successes.
But with all that being said, I did have one bone to pick, the utility of documentation.
Like many software engineers, the author suggests that code should ideally speak for itself which implies that documenting is not a worthwhile endeavour, and then the topic moves on. This is something I hear very often in industry from software engineers, mainly because the code is being developed faster than someone's ability to update the relevant document but also because software engineers simply do not like doing it.
This gives a false impression that it's an outdated tool that should be left in the toolbox. But in my experience it depends very much on the environment you are working in, how you create it and what you expect from it.
If you are working in an environment of strong communication, a stable product and a relatively clean codebase developing at a fast pace, then documentation is probably not worth the added expense. This is the ideal. However, if you work in a organisation with weak communication and suffering from extreme technical debt and a sluggish development speed, then documentation is an invaluable and probably essential tool to use. This is especially true if the organisation has plans to turn itself around where documentation can achieve the following:
- Saving Investigation Time: The author correctly points out that in an environment of extreme technical debt, engineers are often inundated with requests to investigate how a piece of functionality works. A consequence of this continuous tidal wave of requests is that the engineer often does not have time to sensibly refactor or improve that code. So a document here can act as a shield to free up some of that time. Equally, other engineers on the team can find simple answers without time being spent in setting up local environments or requesting environment access.
- Remove single points of failure: Like writing documentation, few engineers enjoy rolling up their sleeves to deep dive into understanding legacy code, and in an environment of extreme technical debt, this task can be quite horrendous. A resulting document here means that if that engineer later walks out the door, which is not uncommon in these environments, the product team does not need to start from zero.
- Bridging tool: Documentation can be a useful tool to bridge that gap from technical debt to a cleaner and stable product. For example, your team could be tasked with refactoring a product feature that is driven by 20 unique scripts that largely do the same thing but contain small bespoke functionality for one or more customers. The first step is knowing what makes those 20 variations unique and a single detailed document can map out and communicate that faster and more accurately than any number of engineers.
Whichever way you lean in respect of your opinion of documentation, writing good documentation is a valuable skill. Do not assume that someone who can write clear software can do the same in plain English for a wider audience to consume. This is an important consideration when judging the utility of your documentation efforts.
I'll end it there 👍
Other reading materials mentioned in the book include:
- User Story Mapping (2015 ) Patton, J. et al
- The Power of Customer Misbehavior (2014) Fisher, M. et al
- Sprint (2016) Knapp, J. et al
Top comments (0)