I was helping to staff the Cloud Native Computing Foundation booth at ChefConf 2018 when the topic of encouraging folks to write articles about what they’re doing with Kubernetes came up. One common problem often encountered is convincing folks that what they’re doing is interesting work. The next problem is convincing folks that writing is not too difficult.
Breaking down the task of writing into three steps is helpful:
- Outline
- Proofread
- Formatting
Having an outline is important when writing any work. It doesn’t have to be fancy if the topic is straightforward for the writer. But, it should exist regardless because it simplifies the writing process. For example, here’s the outline for this article:
- Introduction (Connect with Audience, Use Case, or Identify Problem)
- Outline
- Why an outline is necessary
- What does an outline look like
- What’s the right length for outlines (generally)
- Proofreading
- Tools
- Phone a friend/manager/co-worker
- PRs welcome
- Formatting
- Any style guide requirements?
- Artwork?
- Metadata?
- Conclusion (The Big Takeaway)
In general, try to make three main topic points with no more than three subpoints under them. There is some science behind the rule of three in writing. Credit to Dawn Parzych for pointing this out at DevOpsDays NYC 2018. When doing a deep dive document or article feel free to break this model as needed. But, in general, try to stick to a shorter format for easier consumption.
Pick three points, add an introduction and conclusion and you have the beginnings of a great article.
Proofreading is hard. But, the good news is there are some tools available to help with proofreading. Obviously, re-reading the article is the preferred way to proofread. One suggestion is to take a break between writing the article and proofreading it. Have a meal, talk a walk, meditate, etc. This allows the mind to reset so the writer can more easily see typos or spelling mistakes. There are also two recommended tools for proofreading:
Grammarly: The name says it all but, Grammarly will find the not so obvious mistakes in your works.
Hemingway Editor: Hemingway Editor takes the concepts embued by Ernest Hemingway to make writing easier to digest.
NOTE: If there are other handy tools for proofreading or editing please submit a pull request to this article.
You can also ask for help proofreading. For example, when submitting an article to a site like opensource.com, they have a team of editors and staff available to assist. When in doubt, ask for help. Perhaps a friend, colleague, supervisor or family member has some skills to assist. It never hurts to ask. But, remember, that people edit for a living. Be sure to include a form of compensation for their time.
The last (and sometimes most important) thing to consider when writing a technical article is that there are formatting processes to writing any work. Even a blog post needs tags, categories, and images. When it comes to stock images, there are two sites that have a wide selection of free to use, no credit required works:
Both of these sites have a trending section that allows you to find some high-quality images to use quickly. The formatting, style guide, and metadata are important and often simple things to include in an article. Don’t stress too much about it but, make sure to consider it when writing.
In conclusion, the guidance can be boiled down to this: Think of three points to make in an article; add an introduction and conclusion to those three points. These five points become an outline. The three main points should have a few subpoints plugged in to help stay on topic. Once the outline is built, plug in the missing grammatically bits. Once you have that done align everything to whatever style guide may exist. Tack on the additional metadata and maybe an image then boom! You have a nice, well written technical article.