Technical Writing: Process and Lessons Learned

Posted On December 28, 2021

This is a living document outlining the technical writing process I’ve been using, cobbled together after reviewing the materials provided by clients along with their expectations and comments/feedback received during the editing process.  It will be updated as I learn and tweak things.

This process includes mitigation steps for some of the mistakes I tend to make personally as well as steps specific to who I write for, but hopefully it’s useful for others. Some of the points raised simply come from years of trying to make sense of other people’s tutorials and articles while I learn new tools, languages, libraries, etc.

Steps for Writing Articles

Outline/Research

• Understand the reader 
  • Who are they, what do they do, where are they reading this
• Understand the subject 
  • Find keywords used by the target audience to use for credibility
• Identify what’s valuable to the reader and the value you want to create for the reader
  • What point do you want to leave in the readers mind?
• Figure out roughly what you want to say 
  • Client expectations will be set based on the outline, but the article will most likely diverge from it as it evolves
• While researching the topic note authoritative non-competing resources to link to
• The outline is probably most important step.  It’s where you nail down the knowledge and figure out what to say. Otherwise the draft becomes a disjointed rant that needs a lot of work to fix

Draft

• Focus on the reader, write for the reader
  • Address/engage the reader.  ‘As a successful business, YOU will need to’ not ‘successful businesses need to’
• The initial draft may follow your internal thought process as you come to understand the subject
• Ensure that a second pass is done to redirect that focus on what’s valuable to the reader
  • You cant have the ‘value’ just at the end of the section as thats where your logical conclusion was – lay it out early so the reader doesn’t leave early
    • ‘we found that SOLUTION/CONCLUSION.  We came to SOLUTION/CONCLUSION based on…’ rather than ‘Based on….<insert a lengthly paragraph> We Came to SOLUTION/CONCLUSION’
    • This will likely mean deviating from the outline somewhat to ensure there’s a logical thread and that the structure is organised
• Final Edit for Flow (momentum!)
  • Active voice
  • Remove excess – run on sentences, fragments, redundant phrases
  • Ensure a narrative flow/’red thread’
  • Short paragraphs
    • If a sentence doesn’t work, you CAN just remove it
  • Refer back to the title of the article after each paragraph or two. Are you still on topic ?
  • Bring the article full circle, ensure the conclusion answers the problem posed in the introduction, then end

Step Back!

• Come back tomorrow
• You will need a head clear of any assumptions you made during the drafting process for the next steps

Sense Check

• Taking a hard stance needlessly can harm credibility
  • ‘Process X is never a good idea, Y is much better’ – but is it? Are there situations where X is still superior even if niche? Not being aware of these cases conveys a lack of understanding of the topic
• Maintain credibility by checking any other assumptions, stances taken
  • It may not be necessary to back them up in the text, but ensure they are correct in case someone decides to fact check the article 
  • Link to supporting evidence where appropriate
• Value > Originality
  • You can’t always be original, especially if you’re not a subject matter expert
    • If writing about magnetic storage, you probably can’t go off talking about any novel concepts regarding magnetism that you thought up during the writing process unless you’re a physicist.  Stick to published information, only generate new knowledge for things you fully understand
  • Not all original/novel knowledge is valuable  
    • Nobody knows how many grains of rice are in my kitchen, so documenting it would be original, new knowledge.  Novel information which has no value to the reader
    • Don’t parrot useless existing knowledge to pad things out either
• Avoid doom unless it’s warranted
  • Instead of ‘that outright sucks, this is better’, ‘that is/was good, this is better/this is new and better as it takes lessons from that’
    • The reader may have some investment in the previous thing, don’t want to insult them
    • This language also implies a deeper understanding of the topic
    • Weigh the language of cost vs language of benefit depending on the tone and messaging – ‘Not doing this thing will make you worse‘ vs ‘Doing this thing will make you better’

Final Checklist

• Is the text…
  • Organised
  • Clear
  • Persuasive
    • Easy to read, quick to understand
  • Conversational and/or Authoritative (depending on the context)
  • High Quality
  • Unique 
    • Referring to the structure and language not being a facsimile of another article rather than providing unique knowledge
• Is it actually interesting to read? 
  • Does the intro/excerpt pull you in with an assertion about something the reader cares about/problem to solve and a promise to explain the assertion or solve the problem for the reader? 
  • The reader isn’t being forced or paid to read this and can leave at any time
    • Make sure reading the article all the way to the call to action is worth it for the reader
    • Solve a problem for them…
    • …or be entertaining –  entertainment value is value if the context/client goal for the article calls for it

Submit Article for Editing

• Editors are not fact checkers
  • But leave some notes if you want a sense check on a particular point, people are helpful

Addressing Editor’s Comments

• You’re allowed to disagree with suggestions,
  • However, consider the outside perspective – what is easy for you to consume may look hectic to others

Submit Article to Client (Or Publishing if for Self)

• Client may or may not have their own comments to address prior to publishing
  • The client is paying you to make a point for them to their audience, their requests rule
  • If writing for self, set a reminder to revisit it in a week and check that it still makes sense / accomplishes what you set out to achieve

Notes on Code Examples

• Code examples are for other humans.  Don’t obfuscate for brevity.
  • However, keep it succinct and demonstrate only the point that is currently being illustrated in the text
  • Keep snippets short and readable
• Further context best provided as a working example repo 
  • For example, the code example in an article shows only the relevant API endpoint with the DB query it executes, while the repo contains a full express app with that API endpoint in context
• Be Consistent! 
  • Indentation, semicolons, etc 
  • Consistent logic/flow 
  • Declare and describe a function before you use it
• Comments! 
  • Where the intention of the code may not be clear or a new concept is introduced 
  • Why not how – the code already tells you how
  • Too many comments can visually obfuscate the code itself
  • Code comments should stick to simple, un-nuanced English 
    • Article text can be a bit flowery for flow/engagement – comments must be easily understandable especially for ESL readers
• Function and variable names should make sense – descriptive but not too long
• Provide a framework for the reader to build on so they can get up and running quickly and adapt your code for their use
  • The aim should be to get the reader able to use the feature you are writing about as quickly as possible
• Be aware of code complexity for the intended audience
  • Newbies will require additional context and may need some concepts explained (in the article, not the code comments)
  • Readability
• Does the code work? 
  • Will it work in the future? Mention platform/library versions used so readers in the future know that it may no longer be supported and can check for depreciation
• Standards/Conventions/Best practices followed? 
  • Imports at the top of the file, stuff like that
• Are there any security issues? 
  • Your code will be copied and pasted into someones project  
  • Using a global variable where you shouldn’t could mean they build a leaky app
• Remember- you’re the expert showing someone how to do something  
  • No ambiguous code, logic, comments.

Notes on SEO

• SEO is not my focus
• If keywords provided by client, ensure they are used, however:
  • The article is intended to be valuable to the reader rather than just a keyword jumble
    • Keywords are just an arms race – my focus is on the content
    • Google knows when a user remains on the page and whether they’ve found their answer/value (they continue searching), so focus on that
  • Keywords are good to have, so the search engine knows what the article is, but users arriving via search need to stick around for article to rank highly
  • Keywords should preferably appear in the article preview, headings, and in any image alts/captions – this isn’t just for the search engine, the reader will want to see what they are looking for in the preview/headings as they are scrolling through search results
• Identify backlink opportunities
  • Even if from articles for other clients that will be attributed to other people, propose to them the advantage of sharing links among each other

Notes on Editing

• Be objective
• Do not edit for style or content, it’s not YOUR article

Active Voice Quick Reference

• Use verbs over nouns
• Verbs
  • Use active verbs over passive verbs
    • “Water filled the pool” instead of “The pool was full of water.”
• Nouns
  • Make people act, not concepts
    • “People rarely cry.” instead of “The first reaction is rarely crying.”