Common mistake in software engineering - documentation 📜
In this post, I would like to put down some thoughts on software engineering documentation upon my own experience. Unlike most of public technical articles on my site, this one is going to focus mostly on documentation topic and explain why I consider it as an must-have thing in software industry - aka "Code is hard yet still an easy part in successful software engineering". Stay tuned and read on guys 😎
Couple of weeks ago, I saw this video on Youtube about "Why Software is hard" and the guy's talk really struck me 😍
There are many factors that contributes to difficulty of maintaining sustainable projects in the long run. In this post specifically, I would like to devote all of it for documentation 📄. I'm going to list out reasons with detail on why documentation should be treated like the king 👑 in software project management:
- Documentation is not cup of tea of everyone
- Documentation should be meant for specified readers
- Documentation is underrated as useful tool for onboarding new members
First and foremost, most engineering processes I have known really dislike documenting stuff. In contrast, they are always in favor of free open source projects with a good software license permit and great documentation. This really conflicts the idea of having documentation available everywhere. People seems to take things for granted instead of creating things for community. IMHO, the beauty of teamwork is having supportive mindsets who really are doers instead of talkers. Since software engineering is really not a rocket science, it's very much a collaboration among specialists of all kind - Program Manager, Product Owner, Front End Web, Back End Server, Android Engineer, IOS Developer, and so on. Thus, if you want a sustainable products for everyone to come and work with (that might be your fellows in the future or even yourself), you must provide documentation as part of your work
Second, documentation should clearly target specific audiences. There are variety of documentation such as Product specification, Back End service design system, Front End web components design, et cetera. As an effective writer, he/she should assure the content is appropriate and avoid jargon as much as. We could even pre-define all terminologies as early as possible in the document so that readers will have an easy time to follow. Some company like Google even established an Design Doc Driven culture where everything must be documented before the work can be kick-started
Last but never the least, documentation plays such an important role for onboarding new members regardless of engineering scale. I have known and worked for many companies of various sizes and business models, what stroked me almost every time on the first weeks was how lack of focus they have put on on-boarding documentation. Lately, I took on a responsibility to onboard new member. What I did was totally different from what seen by others. I tried to collect as many specifications as possible about the current product we are about to work on together. The big reason for that is because I strongly believe code is abused as a religion by many software engineers while it should be treated just as a tool to solve certain human's problems. It's always tempting for engineer to jump straight to the code to see how things look like underneath the hood. And that approach has been proven to be problematic over years by lessons learn from many companies. We must start by understanding the problems which we are trying solve before moving on to tremendous amount of possible solutions. One should strive for understanding how system works as a whole instead of every functional hierarchy. Assume that your codebase is well structured and designed by contract - you will be pulled toward related abstraction units to solve your understood problems later anyway. In case your codebase does not make sense, maybe it's time for refactoring 😉
"Documentation as a product" is absolutely a right mindset to have, thanks to Rich Harris (the mastermind behind Svelte and Rollup projects). He presented his talk at JSNation 2022 exactly about that. I absolutely love it 😍
Hopefully, by reading up to this point, you guys are on the same page with me about why documentation should be significantly addressed from the early on and maintained in the long run for any kind of software engineering process. Feel free to reach out to me via email if there are any concerns 😊