28 Structured: Writing Documentation is also a Learning Method #
Hello, I’m Zheng Ye.
Do you write documentation? I know, you may not like writing documentation because in your eyes, it is tedious and a relic of the old era of software engineering.
At first, my impression of writing documentation was not good either.
I started my career at a large company that had passed CMM Level 5 certification. Perhaps many programmers today are unfamiliar with CMM. It stands for Capability Maturity Model for Software and is used to assess the software development capabilities of an organization. It was once popular in China, and many software companies strived to obtain CMM certification.
Documentation was very important in this process-oriented company. However, what I saw in reality was that after a software had already gone live, everyone would start rushing to write documentation to cope with the process.
Each department had a designated process owner who required you to strictly adhere to the document format and ensure the correctness of fonts and font sizes. Then, the document would be printed on A4 paper, sealed in a warehouse, and never to be touched again.
However, documentation is indeed very important. Later, when I visited many companies, the ones where I could quickly get up to speed usually had more detailed documentation, while those lacking documentation often took a long time to consolidate information.
In addition, a large part of my learning about software development and related knowledge usually relies on various forms of documentation. For us programmers, who are at the forefront of the times, reading a lot of documentation is part of our daily work.
Have you noticed the contradiction? On one hand, we dislike writing documentation; on the other hand, documentation plays an undeniable role in our work and learning.
We surprisingly rely on something we dislike so much. Where does the problem lie?
Why don’t you like writing documents? #
Many people would say they don’t want to write those boring procedural documents, and indeed, documents can be boring, which is one reason. However, nowadays many companies have made their documentation quite lightweight, basically only requiring necessary documents. So why do so many people still dislike writing documents?
In fact, the real reason why many people avoid writing documents is that they struggle to structure the content they know well.
In two different scenarios, we play different roles. When writing a document, we are authors; when reading a document, we are readers.
As readers, when we read a document, we are actually following the structure the author has organized, because most of the presented content is already structured, making it easier to read smoothly. But as authors, no one tells us what the structure should be like, so we have to create a structure ourselves, and this is something many people are not good at.
To become a good programmer, having a good knowledge structure is extremely important.
Many people complain that the programming industry is difficult, and the reason is that new technologies emerge constantly. Yes, when your knowledge is scattered, any new technology that comes along is something new. However, when you establish your own knowledge structure, any new thing is just an incremental addition to your existing knowledge.
For example, the currently popular microservice architecture concept is derived from the Unix philosophy of “do one thing and do it well,” while the idea of service-oriented architecture (SOA) is the predecessor of the concept of serviceization. Understanding the motivations behind these concepts, microservices are reduced to problems at the tool level.
With such a knowledge structure, when I need to build an application, I just need to adapt the tools to fit in, and then I can learn the relevant knowledge when necessary, which is very targeted, resulting in a significant improvement in learning efficiency.
There are many ways to structure scattered knowledge, but output is a crucial part of the process.
Knowledge Output #
I don’t know if you have had the experience of explaining problems to your classmates when you were young. Sometimes, even though you have already learned the knowledge very well, you still couldn’t explain it clearly to your classmates. This is because your classmates can always ask questions from angles that you haven’t thought of, and these angles are different from what the teacher taught.
The process of outputting knowledge is essentially the process of connecting knowledge. When you really need to present it in a complete logical way, those missing details will emerge, and filling in these details gradually forms a knowledge map.
The theme of this module is “communication feedback”, and outputting knowledge to the outside world is a way of obtaining feedback. Many people think that they have a deep understanding of knowledge, but when they try to explain it to others, they find that they can’t explain it clearly. This indicates that their understanding is far from what they thought.
There are many ways to output knowledge, and for programmers, the two most common ways should be writing and speaking.
When you read many books and technical articles, these are the results of others’ output through writing. And in many technical conferences, there are often various experts sharing their gains on stage, which is the way of output through speaking.
Many master programmers in the software industry are adept at outputting to the outside world. For example, Eric Raymond, the proposer of the open source concept, opened the door to open source with his book “The Cathedral and the Bazaar”. Kent Beck, who has been mentioned several times before, wrote several books such as “Extreme Programming Explained,” “Test-Driven Development,” and “Implementation Patterns”.
Martin Fowler is almost a model of external output. He has reorganized many seemingly false concepts, giving discussions more standardized vocabulary, such as refactoring and dependency injection.
Going further back, we have to mention Donald Knuth, the author of “The Art of Computer Programming”, who systematically organized the concepts of algorithms. In order to write well, he even created a typesetting software called TeX.
Perhaps you would say, “That makes sense, but I’m really not good at it!” It’s because you haven’t mastered the basic methods.
The Pyramid Principle #
First of all, it is important to clarify that our first goal is not to become a writer or a speaker, but simply to express things clearly and present our knowledge in a clear manner. So, let’s start by understanding the Pyramid Principle. Take a look at the image below, and you’ll get the idea:
First, we need to determine what we want to express, which is the central argument. Then, we determine the supporting sub-arguments for this central argument, and finally we find the evidence that supports each sub-argument.
From the central argument, sub-arguments to evidence, this unfolds layer by layer, and structurally it looks like a pyramid. Hence, this method is called the Pyramid Principle.
Take our column for example. Our central argument is that “efficient work can be achieved by following certain methods”. The sub-arguments supporting this central argument are our four principles, and for each principle, we provide various practices and thoughts as evidence.
As mentioned earlier, a person’s inability to effectively communicate is often due to a lack of structured knowledge. Now, through this method, we can help ourselves structure knowledge. Once we have the structure, the next step is how to communicate it.
The specific way of communication can be chosen according to personal preference. Either express it from top to bottom, i.e. start with the central argument, then discuss sub-argument 1, provide evidence to support sub-argument 1, then discuss sub-argument 2, provide evidence to support sub-argument 2, and so on.
Or express it from bottom to top, first derive sub-argument 1 from the evidence, then derive sub-argument 2, and finally summarize and conclude with the central argument.
It may sound simple, but don’t think that understanding the Pyramid Principle means you have mastered everything. You still need more practice.
Practice makes perfect #
I used to be very bad at writing and public speaking, but these things are improved through a lot of practice. My external output started shortly after I started working. At that time, blogging was popular, so out of curiosity, I embarked on my own blogging journey.
When I first started blogging, I would share what I wrote with friends around me. They would provide feedback, including praise, teasing, and discussions on certain details. This made me feel that there were people who read what I wrote, and it gave me the motivation to keep going.
I also admired people who were good at writing, so I would often imitate their techniques to constantly improve my writing skills. Gradually, my readers expanded beyond the people around me, and I received more feedback.
It was through this feedback that I gained a whole new understanding of many things, and it gave me a stronger motivation to share. A positive cycle gradually developed. Eventually, writing became a habit of mine, and I have been consistent with it until now.
Through the practice of writing blogs, I developed my own structure and style, which opened up more opportunities for me to write in different places: writing articles for magazines, writing on websites, including this column today, all originated from my initial blog writing.
In addition to the readers’ praise over time, I also gained more opportunities. For example, my first public speaking experience came from an invitation from a reader of my blog.
Some career opportunities later on also came through friends I met through blogging. Considering that I was on the outskirts of the IT industry in the northeast at that time, my career development to what it is now is largely a result of years of consistent external output.
Similarly, public speaking skills require a lot of practice. In 1977, the magazine “Book of List” conducted a survey on the “worst fears,” and public speaking ranked first, surpassing death. So it is normal to be afraid of public speaking.
I still remember how my hands were shaking during my first public speaking experience. Looking back now, it was quite silly. The first time I spoke at a conference with hundreds of people, there was a period of time when I only focused on the big screen, with my back to the audience, which was quite embarrassing.
I always admired those who spoke confidently on stage, like Steve Jobs. It wasn’t until I read “The Presentation Secrets of Steve Jobs” that I realized even someone as talented as him had practiced extensively for his speeches.
My own public speaking became more normal after I went through a lot of practice during a consulting project. At that time, I had to explain things to clients almost every day, which forced me to continuously prepare and speak. So, essentially, the fear of public speaking is only due to insufficient practice.
Well, now you understand the essence of acquiring these skills: practice makes perfect!
Summary #
Programmers have a contradictory feeling towards documentation. On one hand, they rely on documentation to gain knowledge, but on the other hand, few are willing to write documentation.
Documentation has a “bad reputation” in the minds of programmers, mainly because traditional processes require excessive and useless documentation. However, for many people, the unwillingness to write documentation is fundamentally due to the lack of a good structure for organizing knowledge.
Structured knowledge makes it easier to learn new knowledge. Many complain about the constant influx of new knowledge today because the knowledge is too fragmented. When knowledge is structured, learning new knowledge becomes a process of learning increments, and efficiency naturally improves significantly.
Outputting knowledge is a great way to connect different pieces of knowledge. Writing and public speaking are both excellent ways to output knowledge.
One significant reason that hinders many people from outputting knowledge is the lack of a model for outputting. The Pyramid Principle provides a model from central arguments to sub-arguments and supporting evidence, which helps us organize knowledge.
To excel in knowledge output, continuous practice is also necessary. Both writing and public speaking can be improved through practice.
If there is only one thing you can remember from today’s content, please remember: Output more and give your knowledge structure.
Lastly, I would like to ask you to share your thoughts on opportunities in your work where you can output your knowledge. Feel free to write down your ideas in the comments.
Thank you for reading. If you find this article helpful, please consider sharing it with your friends.