Technical Writing: Process and Lessons Learned

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


  • 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


  • 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.”

Leave a Reply