Paragraphs
In this topic, you'll explore the importance of concise and scannable paragraphs in technical documentation.
You'll learn about maintaining a word count of 50-150 words per paragraph, balancing context with readability.
Minimum length for all paragraphs
Give your paragraphs room and keep them short. The idea is to make your content easy to scan, so the recommended word count is 50-150 words.
This range is the "just enough" or "ideal" range because it provides enough context without overwhelming the user.
Here's an example of what 103 words looks like:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque convallis dapibus tempus. Aenean finibus sit amet ligula id congue. Donec id velit lacinia sapien molestie congue. Aliquam id dui vitae augue maximus tempus. Mauris at malesuada ante, ac imperdiet nisi. Donec dapibus tellus justo, ac rutrum lorem imperdiet porta. Fusce. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque convallis dapibus tempus. Aenean finibus sit amet ligula id congue. Donec id velit lacinia sapien molestie congue. Aliquam id dui vitae augue maximus tempus. Mauris at malesuada ante, ac imperdiet nisi. Donec dapibus tellus justo, ac rutrum lorem imperdiet porta. Fusce.
Introduction paragraphs
Think of the introduction paragraph for the topic as the Abstract of an essay or research article—it's a brief summary of the content's key points.
However, for the headings and subheadings within the topic are meant to briefly describe the section.
It's recommended that all topics and the section headers have an introduction paragraph. It provides enough information for the reader to decide whether to read or continue scanning the content. Users likely don't have time to sift through mountains of information.
Avoid starting with phrases such as "This topic describes..." or "This topic is about...."
Instead, use something like, "In this topic/guide, you'll do XYZ (what they will accomplish by the end).
Correct
In this topic, you'll set up a CI/CD pipeline using Jenkins. As you walk through the initial setup, you'll learn how to automate your build and test processes and efficiently deploy code changes to your prod environment. By the end, you'll have a fully functional CI/CD pipeline that accelerates your software development and deployment workflow.
Why this is better: This example gives the reader a clear outline of actions and outcomes.
Incorrect
This topic describes how to set up a CI/CD pipeline using Jenkins. It will cover the initial setup, the process of automating builds and tests, and the deployment of code changes to production. This topic is about providing you with the knowledge to create a CI/CD pipeline that improves your software development and deployment processes.
Why this doesn't work:This example passively describes the guide's content, making it less inviting and engaging.