Before getting down to the actual writing part of documenting another one of your open source projects, and even before interviewing the experts, it's a good idea to answer some high-level questions about your new document.
Renowned communication theorist Harold Lasswell wrote in his 1948 article, The Structure and Function of Communication in Society:
[A] convenient way to describe an act of communication is to answer the following questions:
- Who
- Says what
- In which channel
- To whom
- With what effect?
As a technical communicator, you can apply Lasswell's theory and answer similar questions about your document to communicate your message better and with the desired effect.
Who—Who is the document owner?
Or, what company is behind the document? What brand identity does it want to convey to its audience? The answer to this question will significantly influence your writing style. The company may also have its own style guide or at least a formal mission statement, in which case, you should start there.
If the company is just starting out, you may ask the questions above to the document's owner. As the writer, it's important to integrate the voice and persona you create for the company with your own worldview and beliefs. This will make your writing sound more natural and less like company jargon.
Says what—What is the document type?
What information do you need to communicate? What type of document is it: a user guide, API reference, release notes, etc.? Many document types will have templates or generally agreed-upon structures that will give you a place to start and help ensure you include all the necessary information.
In which channel—What is the format of the document?
With technical documents, the channel of communication often informs the final format of your doc, i.e., whether it's going to be a PDF, HTML, a text file, etc. This will, most likely, also determine the tools you should use to write your document.
To whom—Who is the target audience?
Who will read this document? What is their level of knowledge? What are their job responsibilities and their main challenges? These questions will help you determine what you should cover, whether or not you should go into details, whether you can use any specific terms, etc. In some cases, the answers to these questions can even influence the complexity of syntax that you should use.
With what effect—What is the purpose of the document?
This is where you should define what problem(s) this document is expected to solve for its prospective readers, or what questions it should answer for them. For example, the purpose of your document can be to teach your customers to work with your product.
At this point, you may refer to the approach suggested by Divio. According to this approach, you can assign any document one of four types, depending on the document's general orientation: learning, solving a problem, understanding, or getting information.
Another good question to ask at this stage is what business problem this document is meant to solve (for example, how to cut down support costs.) With a business problem in mind, you may see an important angle for your writing.
Conclusion
The questions above are designed to help you form the basis for effective communication and ensure your document covers everything it should. You can break them down into your own checklist of questions and keep them around for whenever you have a document to create. This checklist may also come in handy when you become stuck, confronted with a blank page. It will hopefully inspire you and help you generate ideas.
Comments are closed.