The Science of Technical Writing
As engineers, technology specialists, and technicians in our respective fields, good structured writing skills are not always a requirement for our jobs; but writing well can still be important. It can determine how people understand our roll in the organization and the roll of processes in the overall workflow of the company. Whether technical writing, developing support concepts for a grant, or explaining an incident; being able to coherently pass along technical ideas to others is critically important.
That said, writing doesn't come easy to everyone; and building written materials can be something that when not practiced regularly or as a common responsibility in the job can be difficult and time consuming. Using a structured process over a creative one can help this. Even inexperienced writers can be more coherent and effective without wasting a lot of time if they use a logical process and a flow when creating first drafts.
Using methods such as those in this article help create a structure that a reader can follow; but also assists to alleviate the creative stopping points that writing from beginning to end sequentially can cause. Its slightly slower than just writing beginning to end; but more versatile, keeps information organized, and helps focus on the critical points that need to be made.
------------------
Step 1: List facts, key points, steps, or events as bullet-ed items on paper without structure or concern for syntax before writing, and then organize them later.
It's important to get all the ideas down first. Brain-storming is a critical part of the creative process but can be done in many ways that don't require as much creative effort. For example, writing lists quickly and just notating how it relates, writing out key objectives, or listing the appliances and resources effected is a good starting point.
Step 2: Make "buckets" using the topics or concerns in step 1. Go through your lists and push facts, content, and information under the structured categories to organize them. Use these as paragraphs in the document.
If something is completely out of line with any core point; it needs to be removed. (No matter how interesting or important) This is also a good time to separate procedural steps from the explanations about how or why something works. Steps should be easy to reference, follow, and require little or no judgement be made on the part of the reader; while explanations need to present arguments and justification in a structured way in their respective categories.
Step 3: When actual writing starts, follow standard paragraph structure, keep it simple, consistent, and don't try and sound "technical" or "sterile". Make a new paragraph if a lot of information has to be addressed.
Structure isn't just for the writer. Readers need structure to be able to anticipate what is written. There is the old process we learned in school; create a topic sentence from your core topics lists; setup two or more primary support sentences for each topic; then one or more secondary support sentences explaining these concepts further. But this isn't the only valid structure. It can be changed if the writing itself is consistently done through every paragraph in the document and done in a way the organization or audience can understand.
Step 4: In drafts, avoid literary flotsam, and pointless exposition. Get the facts solid and well organized.
While a paper shouldn't read like a legal document, a lot of literary tools to make papers more exciting are better added conservatively in the final draft after the content is solid. Written materials need to be clear and understandable, but it's a common flaw in writing to add fluff when hitting a stopping point. These are often "zero-add" to the final product and sometimes detract from the point.
Some common "zero-add" written habits include asking questions, then answering them, "You know what I mean? Of course you do." Using onomatopoeia, exclamations, or interjections to try and make your written documents "Pop!" or "Snap". If you want to teach a concept, avoid using a lot of acronyms and cliche catch phrases, just create a simple narrative and use common language without a lot of acronyms.
Step 5: Do introductory and summary paragraphs last.
The hardest part to writing can be starting. Fortunately, this is the least important part of the material and writes easier once everything else is done. Early drafts need to be accurate, concise, and easy to understand. Secondary drafts correct spelling errors. Two quick paragraphs can introduce the material and another can be added at the end to summarize. If done well, often these are just restating points made in the document itself.
The 5 basic steps work that for me:
- List all my facts, key points, and relevant events first unstructured.
- Organize my concepts into the broad topics I want to address.
- Build a standard and consistent paragraph structure in my first draft.
- Keep it dry in early drafts and clean it up later.
- Do introductory and summary paragraphs last.
The steps here aren't the only way to write well or produce readable documentation. But they produce consistently similar quality content with minimal effort.