How to get started writing
We'll cover the following
What is an outline?
An outline is an initial layout of your document. It will help you organize your ideas and visualize the structure of your document. Once you begin to write, your outline will help you to stay on track and not sway from your document's purpose.
Note: It can be tempting to skip the outline step, but we advise against this, especially when you are a beginner. Without an outline, your writing project can quickly get off-topic, become much longer than intended, exclude vital information/include unnecessary information, or become disorganized. An outline will streamline your writing by organizing your thoughts and ideas from the start.
How to outline
Before you begin writing your outline, you must have an understanding of:
The purpose of your document
The audience for your document
If you do not know the answer to one or both of these statements, you need to go back and clarify why you are writing this piece of documentation. As a developer, the answers to both of these statements will usually be clear to you based on the type of document you are writing. But always make sure that you are clear on these two things before you begin anything. If you don't, you may find yourself struggling to keep your document within its intended scope. Once you know the answers to these statements, write them down and place them at the top of your outline.
Next, write down each and every question that your intended audience may have about the subject of your documentation.
For example, let's say you work for a content creation company and you are outlining a software requirements document for a new plagiarism-checker product that will automatically check for plagiarism on any content created on your company's platform.
Example 1
The questions your audience may have are:
What are the expectations for the outcome of the product?
Who is the product's intended audience?
What problem is the product solving?
What are the goals and objectives for the product, and how do these relate to the company goals?
What will the user's needs be for this product?
What variables are there going into this project?
Are there any assumptions you've made regarding the product that may turn out to not be true or otherwise cause an error?
What is required for the product to build?
What UI/UX requirements should be considered while building?
How many additional features would be required for the product to work successfully?
What else would be needed?
Depending on your audience, more information may need to be provided. It is important that you re-check the questions you laid out for yourself at the beginning. Did you miss anything?
Now, it is time to answer the questions we laid out. When answering your outlined questions, it is important to keep your intended audience in the forefront of your mind:
What is the knowledge level of your intended audience?
What are the specific goals of your intended audience?
Why does your audience care?
It is important to know the answers to these questions to ensure that you do not sway from the purpose of your document.
When answering the questions in your outline:
Make sure that each answer has the appropriate background for the audience's understanding. Adding bullet points for all the background information that should be included will make it easier to visualize your document ahead of time.
Make sure all necessary terms are defined in your outline. It can be very easy to forget what terms are clear and what terms are not once you actually get down to writing. Help yourself by providing a realistic roadmap for the document at hand.
Example 2
Let's take the first three questions from the example above. If we were to go through and answer those questions, assuming that the intended audience is your team, it would look something like this:
What are the expectations for the outcome of the product?
The outcome of this product will be the ability to check for plagiarism with a higher level of accuracy than can be acquired through unpaid tools.
Who is the product's intended audience?
Content creators who want to check their content for plagiarism before submitting. Additionally, internal content creators and review team members who want to ensure that no plagiarism is present on published content.
What problem is the product solving?
As reported by the content team, copyright issues have increased due to the unreliability of the current, free plagiarism checker used by the company. This is causing an increase in work for our legal team and making it difficult for our staff content creators and review team to ensure 100% originality in published content.
Context needed: Direct issues caused and the time cost it incurred for the content and legal teams.
As you can see, the answers to these three questions are in no way enough to clarify the purpose and requirements of the product. However, each answer requires more explanation, either around process, reasoning, or requirements.
Now, take a look at the list of questions in Example 1. Notice how many of these questions will be answered once you finish answering each outline question you laid out.
Outlines helps you see the logical flow of information you will present in your document and makes it easier for you to begin writing your documentation.
At this point in the process, you should have your purpose and audience defined, along with the answers to the questions that the document must answer to satisfy the purpose. You are now ready to organize your outline.
How to organize
Proper organization of your outline is critical to ensure the proper organization of your final written product. When organizing your timeline, keep in mind that technical documents should be concise and place the most important information first. Also, keep in mind that the documentation you are writing may have a pre-determined format. If you are unsure, ask your manager for further guidance.
To organize, ask yourself the following questions:
What information does your audience want to know the most?
What information does your audience need to understand the answer to question 1?
Now, take another look at the questions you have laid out to answer and re-arrange them based on the answers to the two questions above. If, while organizing your timeline, you realize that one of the questions you have listed for your document is outside of the scope of your document, get rid of it! That is one of the benefits of an outline; it allows you to zoom in on what you are planning to write and get rid of any unnecessary information.
If your document requires a specific format, do not re-arrange the information presented in your outline. Instead, make sure that all the points in each section of the document are written in the clearest and most logical way for your audience to understand.
In the next lesson we will learn how to write well, starting with the basic construction of sentences and paragraphs.