- Published on
Effective Technical Writing - Purpose
- Danny Mican
Technical writing requires a clear understanding and definition of purpose. Technical writing that lacks a clear purpose will be unfocused, confusing or even misleading. Effectivie technical writing has an explicit and well defined purpose. A well defined purpose becomes even more essential for space constrained mediums such as tweets, messaging (such as Slack) and email.
Effective technical writing often addresses 1 of 3 primary purposes, functioning as:
A purpose is a reason that something exists. Understanding the purpose of a piece of writing helps inform the rest of the writing process and helps to set the context for creating an effective written artifact. In a professional technical setting meandering, random, poorly-defined technical documents can be a distraction and a time-waste. A document with a clear purpose allows the reader to level-set and allows you to craft the document in a way that best conveys that purpose.
An informational writing should allow the reader to walk away with a better understanding of a given situation or event. Effective technical writing should leave each reader with a similiar understanding. Informational writing is unambiguous and clear.
Examples of informational writings include:
- Status updates
- Reflection documents
- Playbooks / Runbooks
- Decision documents
Each one of these should leave the target audience with a better understanding of the world, or enable the target audience to perform an action. Informational documents are a "current-looking" focusing on the state of reality at a point in time.
A peruasive document attempts to convince somebody of something. Persuasive documents include:
- Request for Comments / Discusssion
Persuasive documents often have forecasts on how changes may affect the current state. A good proposal should provide the target audience with the goal and the effect that the proposal has. Proposals need to provide sufficient supporting context, but also forecast how the proposal can affect the future. Proposals are forward looking in nature.
Any purpose can provide an opportunity for collaboration between multiple people. Collaborative documents are exploratory, focused on building an understanding of a given situation with a group of people, and potentially agreeing on a course of action for that situation. A collaborative writing is a great excercise to help build understanding, work closely, kick off ideas and provide feedback on others thoughts. Any type of writing has the opportunity to provide a foundation for collaboration.
Purpose is an extremely important concept in technical writing. A clearly defined purpose will provide a foundation for refrence for each subsequent phase in the writing lifecycle.