Editing and Gathering Feedback

Daryl White
Editing and Gathering Feedback
Page content

Credits:

  • Image credit: Photo by Moose Photos from Pexels
  • I would also like to thank the tech writers in the Write the Docs Slack’s #lone-writer channel for bringing these ideas to the top of my mind.

Everyone suffers from a bias of familiarity when looking at our docs. Once you read something once, the next time you read it the mind can anticipate and insert what it remembers and expects to be there. This happens whether the expected word or phrase or punctuation is there or not.

This is why having someone edit what you have written is very important. Our own familiarity with what we wrote - or what we intended to write - makes it very difficult for our minds to notice what is missing or incorrect.

But what do you do when you are the only writer for your docs?

Editing your own writing

There are a few tricks to you can use to edit your own writing.

  • Walk away for a while. This could be for a cup of coffee or a night’s sleep. Or it could just be switching tasks to something else before coming back. Give your brain a break from this job and you can come to it with fresher eyes.
  • Change the format of the docs. Print them out instead of reading them on a screen. Read them out loud. Change the font, font size, color, or page margins. Any of these can be enough to help your brain consider the writing in a different way.
  • Change your body position. Stand up rather than sitting. Read them on a different device so that you can look down instead of straight ahead. Take your laptop and move to a couch or a different space in the office. Again, the idea is to make the experience different enough for your brain to consider it new and worth paying attention to.

At the end of the day, though, you are still going to suffer from familiarity with the docs. As a former boss of mine was fond of saying

There’s always another edit.

Seeking feedback from others

The best solution is to develop relationships with others who can look over what you have written and apply their red pen.

  • Subject matter experts can make sure you are not telling inadvertent lies
  • Someone in marketing can make sure your voice and tone fall in line with brand standards
  • A QA team member can verify you covered all the required steps
  • Customer support can check if you are missing addressing important questions

As you work with other people, you can discover others who have a knack of understanding the grammar, word choice, and voice well enough to provide feedback. Tap into their skills. Make sure they have the bandwidth. Seek approval from their management team if there is going to be a lot of time involved.

Make feedback easy

Our company’s primary communication tool is Slack. After starting, I reactivated a dormant documentation channel and started posting to it. I made sure people were aware of it and linked to the channel often when posting elsewhere. Then I started asking people to make their requests for updates to the doc in that channel. This helped people have a central place where they could see if someone else had already made the same request. It also helped me have just one place to look to for tasks.

As a small company, I wanted to make sure everyone had access to making suggestions. Not everyone had access to create an Issue on GitHub, so that was out as a common place. For my situation, Slack made the most sense. But consider the tools your team has available and choose one that most people already use regularly.

Remember to keep the feedback easy. I needed to make sure I knew where the requested change needed to go. The easiest answer to that in my case was to ask for the URL of the page that needed changing. But I found that the person requesting the change did not always include enough information for me to determine where the change needed to take place.

So I made a form.

Then I made the form super easy to access, right in the channel where I was already sending people to when asking for a doc change.

How did I do it? With a Slack Workflow Builder request.

Creating a Slack Workflow

Prerequisite

Slack Workflow Builder requires a paid Slack plan

Building the workflow

  1. Click your Slack community name, select Tools, then select Workflow Builder
  2. Click Create
  3. Give your new workflow a description, then click Next
  4. Select Shortcut
  5. Make the following entries:
    • Select the channel where you want to form to be available
    • Give the form a name
  6. Click Save
  7. Click Send a form, then make the following entries:
    • Add the form questions
      I added three:
      1. What kind of change are you requesting? (A dropdown with limited options)
      2. What is the URL of the page that needs updating?
      3. Describe the requested change in detail.
    • Select to send the submitted responses to a channel
    • Select your doc channel
  8. Click Save
  9. Select Send a Message
  10. Add yourself as the recipient and enter a message text
    The Slack Bot sends you the message when someone adds a request.
  11. Click Save
  12. Click Publish

Using the workflow

Now users can click on the lightning bolt icon to access channel shortcuts when they are in your channel. They’ll select your flow from the list, answer your questions, and submit it. Then you have a record in the channel and in the Slack Bot that the request happened.

I add a checkered flag emoji to the message in the channel once I have finished working on it. It helps me and the requester know whether the task was done.