1. Writing Matters as Much as Writing Code
From a behavioral standpoint, writing and coding are both typing; the only difference is that writing addresses people while coding addresses machines.
Coding exists to control the state of a machine and make it transition according to preset instructions; writing exists to convey knowledge and let other people understand according to preset logic.
So coding and writing are in fact two very similar modes. At the same time, for an engineer, writing is as important as coding.
For a learner, listening, speaking, reading, and writing are basic skills that cannot be avoided. Through listening and reading, you take in knowledge; through speaking and writing, you put knowledge out.
Teaching and learning promote each other: while putting knowledge out, the teacher also improves further. Writing is one of the most important parts of that.
Writing can deepen your understanding of knowledge, improve your self-expression and personal influence, make your thinking clearer, and make your grasp of a problem more thorough. Below, let’s look at how to write technical articles the way you write code.
2. Choose a Good Topic - Find the Need
Choosing a good topic means identifying your target audience and writing in the direction you are best at and most interested in. Here are some directions for reference:
- Frontier trends
Frontier trends can be traced in the front pages of tech media, GitHub Trending, Google Trends, mainstream industry public accounts, CNCF conferences, and so on. If you keep an eye on the industry, frontier trends are a good choice. For example, edge computing, Serverless, and the like.
- Product introductions
Choosing a promising product and bringing it in front of the right people is a wonderful thing. Many people fail to use a product simply because they do not know it exists. As an evangelist, you can deliver enormous value to everyone.
- Technical optimization
At work you run into technical bottlenecks, and through step-by-step optimization you eventually solve the problem. Recording the process of solving it, thinking about what caused it, and uncovering the potential risks are all very important to the business.
- Study notes
Do not casually copy and paste fragments of knowledge and save them as study notes — that is not knowledge you have mastered. Write your study notes carefully, as if you were writing documentation; only then can they merge with your existing body of knowledge.
- Competitor comparisons
Comparing the differences between products on the market and giving an assessment result will strongly test your depth and breadth of knowledge in the field. But competitor comparisons are the direction people are most willing to read and discuss.
- Scenario applications
For a given product, its different uses in different scenarios, practiced over and over. This is a topic direction with a very high output rate.
- Reflections and takeaways
Work, industry, and life all need periodic review. Time can only give us breadth; self-examination is what gives us depth.
3. Lay Out an Outline - Design the Architecture
3.1 Summary-then-subtopics
“R&D Is Like Drilling Troops, Operations Is Like Deploying Them”
- Thought drives behavior
- R&D is like drilling troops
- Operations is like deploying them
First give a summary description, then introduce the related modules in detail one by one, taking down each in turn.
3.2 Lab report
“Stress Testing Kubernetes Dynamically Creating Jenkins Agents”
- Cluster configuration
- Jenkins configuration
- Test strategy
- Test results
- Test summary and recommendations
First give the prerequisite configuration, then describe the execution process, obtain the execution results, and finally summarize and comment. A faithful recorder, without any emotion, just like a lab report.
3.3 Parallel enumeration
“Docker Tricks You Did Not Know”
- Staged builds
- Building with the cache
- Packaging applications with S2I
- The .dockerignore file
- Saving a container as an image
Around a single theme, use parallel structure and keep enumerating evidence, in order to emphasize the theme.
3.4 Story-led
“Operations Is No Longer a Matter of Gut Feeling”
- Operations is no longer a matter of gut feeling
- Fine-grained operations to understand user behavior
- The magic of short links
- Download links can be put to work too
First grab attention with a novel description, then lead into the theme, give the core viewpoint, and build several supporting arguments.
3.5 Comparative discussion
“Building Cloud Native Applications with S2I”
- What problems S2I can solve
- The characteristics of S2I
- How S2I differs from buildpack
- Trying S2I
Through comparison, differentiate the topic from similar ones, and with the help of those similar topics, quickly enter the reader’s mind.
3.6 Progressive optimization
“How to Get the Client’s Real IP in Kubernetes”
- Create a backend service
- Get the real IP by accessing through NodePort directly
- Get the real IP by accessing through LB -> Service
- Get the real IP by accessing through LB -> Ingress -> Service
- Summary
Around one problem, do not give the best solution directly; keep optimizing the solution, lay out the route of optimization, and show how the logic evolves. One wave has not yet subsided when another rises, full of ups and downs, tossed between annihilation and hope — how wonderful is that.
3.7 Interview Q&A
Q: What is DevOps
A: DevOps is a culture
Q: Why do we need this culture
A: …
One question and one answer, like Plato or Confucius, expounding ideas through dialogue. From a third-party perspective, in the form of questions and answers, express your viewpoints.
4. Fill In the Content - Implement the Code
I recommend reading Ruan Yifeng’s style guide for Chinese technical documents.
A brief list of the points I pay more attention to:
- Sentence breaks. Whether or not a break is strictly called for, I add punctuation where appropriate, so that a sentence never runs too long without a pause.
- Distinguishing “地” from “的”. Use “地” before a verb and “的” before a noun. This is also a small trick I use to check whether the wording in a document is accurate.
- Add spaces before and after English words and numbers. It looks more pleasing.
- Avoid ambiguous descriptions. Even with a 99.99% probability, do not describe something as certain.
- Prefer objective descriptions. Use keywords like “I think” and “I feel” sparingly.
5. Matrix Distribution - Ship and Operate
Once we have the article content, we have completed the transformation from the intangible to the tangible, and we have our first medium of distribution. Based on the document, we can keep expanding the media: turning it into a series of articles, a book, short videos, long videos, livestreams, talks, courses, and so on.
Then comes how to reach users. Here are some places where tech users commonly gather:
- Search engine recommendations, SEO
- Baijiahao, Toutiao, CNBlogs, CSDN, Tencent Cloud Community, Jianshu, InfoQ, TWT, Reddit, Medium, Dzone
- WeChat Moments, WeChat groups, QQ groups, Weibo
- Douyin, Kuaishou, WeChat Channels, Bilibili, YouTube
- V2EX, Zhihu, LinkedIn, Twitter, Facebook
6. Continuous Development and Operation
A good system is built by iterating and optimizing continuously, and by cultivating users continuously. There is no need to care about the starting point, and no need to care about speed; as long as you have chosen the right direction, keep at it and you will reap something beautiful, because persistence itself is something well worth remembering.
Advance one pawn a day without end; no effort is ever wasted, and in time it all flows into the sea. However small the progress, however small the effort, over time it too becomes very meaningful.
People tend to magnify short-term effects while ignoring long-term ones. May we both be long-term guardians, continuously investing passion and continuously tending and refining, so that one small thing after another becomes wonderful.
Yes, I am talking about writing.
