Author Archives: Sarah Maddox

The power of a doc plan or design doc

For a while, I’ve been thinking about the joys and pains of writing documentation plans (doc plans). It takes a long time to write a doc plan and get it approved. It’s time that you could spend writing the real docs — that is, the user guides, developer guides, API guides, and so on, that constitute our bread and butter as technical writers. Are doc plans worth the time we spend on them?

After careful thought, my conclusion is this:

Doc plans are a technical writer’s power tool. We use them to craft a shared understanding between ourselves and our stakeholders. What’s more, as technical writers, we’re well qualified to write an excellent doc plan.

In many cases, a doc plan does more than define the docs that need to be produced. The doc plan fine-tunes the engineering team’s goals for and design of the product itself. Sometimes, indeed, the doc plan represents the first time anyone has attempted to present a coherent picture of the product’s customers and their needs.

Hint: If your reviewers and approvers are primarily engineers, think about referring to your doc plan as a design doc instead of a doc plan. Engineers know the design doc pattern. They know the purpose of a design doc, and how to review it. This familiarity will make them more comfortable when reviewing your doc plan, and could therefore result in more useful and appropriate feedback.

How do you write a doc plan?

The first steps for writing a doc plan are the same as those for any other document:

Define the purpose and audience of the doc.

Before you start, think carefully about your goals. What you want to get out of the doc plan? What do you want your stakeholders to understand and approve?

If you can’t answer these questions, then maybe you don’t need a doc plan at all. Instead, would it be enough to jump straight into the documentation update and rely on the review and approval process for the documentation itself?

Writing a doc plan should be a purposeful and therefore enjoyable part of your tech writing process. You should feel excited about getting a good, clear decision and about honing your understanding of the problem that your documentation will solve. You should also feel excited about explaining your proposed solution to your stakeholders. If the process of writing the doc plan feels like a nuisance, then the process probably needs changing.

Here’s a summary of how to go about writing a doc plan. The process will probably look familiar, because it’s similar to writing other types of documentation:

  1. Define the purpose of and audience for your doc plan. I discussed this in detail in the paragraphs above, and it’s worth repeating here.
  2. Gather requirements by reading related docs and specifications.
  3. Talk to stakeholders, subject matter experts, and your own team.
  4. Scribble diagrams to cultivate your own understanding of the requirements. These diagrams will most likely be user flows that show how people will complete one or more tasks using the product that you’re documenting. Don’t throw these diagrams away! They may be useful in your doc plan.
  5. Scribble more diagrams to cultivate your proposed solution. These diagrams will most likely be conceptual illustrations of the information architecture in your documentation site, and user flows showing how people will find and read information in the documentation. Hang on to these diagrams too. They’ll almost certainly be a useful part of your doc plan.
  6. Plan the docs that you need, down to the page level, based on the above diagrams. Be aware that the detailed design is likely to change when you start building the docs. At this stage, the page-level detail is useful for estimating the amount of time required to complete the documentation update.
  7. Put it all together as a doc plan. The next section has some guidance on what’s in a doc plan.

What’s in a doc plan?

What you put in your doc plan depends on what you want to get out of it. As discussed in the previous section, think about your goals for writing the doc plan. Those goals determine what you’ll include and what you’ll leave out.

Your organization probably has a template or two for doc plans. The internet offers some templates too. I’ve linked to a few templates and examples at the bottom of this post. In my experience, templates are useful as a starting point, but I almost always remove some sections and add others of my own, based on what I need for each particular doc plan.

Here are some useful sections to include in a doc plan:

  • Title (for example: ProductFoo doc plan, or Doc plan for migration from Foo to Bar)
  • Author
  • Summary of the purpose of the doc plan (very short, just one or two sentences)
  • Other metadata:
    • Status (draft, under review, approved, etc)
    • Date created
    • Reviewers and approvers
    • Other items that are specific to your environment, such as a short link to the doc plan, your team name, etc
  • Introduction (context, including a reference to existing documentation if you’re proposing and update to an existing site, the project or product that the documentation applies to, and other background information)
  • Goals and non-goals (a clear description of what you want the documentation updates to achieve, the scope of the documentation updates, and what’s out of scope)
  • Use cases (also known as user flows; diagrams are useful here)
  • Detailed design for each use case
    • Structure of the documentation site (information architecture; diagrams are useful here)
    • Description of the content required, down to the level of a page (deliverables)
  • Implementation phases and timeline (estimates of when the content will be ready for publication, based on an assumed level of staffing)
  • Measuring the results (metrics, user studies, and other ways of determining the effect of the documentation delivered)
  • Dependencies and related projects

I’ve highlighted in bold the sections where we as tech writers may feel most comfortable and most excited. These are the sections most closely related to the design and creation of the documentation. Yet the other parts of the doc plan are equally important. In fact, they’re key to getting buy-in from our stakeholders.

How comprehensive does the doc plan need to be?

There’s a lot of other information that could go into a doc plan. For example:

  • Risks, including assessment of potential impact and mitigation
  • A detailed staffing plan (the writer(s) who’ll create the documentation)
  • Alternative designs that you’ve considered and discarded
  • A plan for translation/localisation of the content
  • A log of updates that you’ve made to the doc plan

My recommendation is:

Include only what you need. If you’re not sure, cut it out.

If you’re starting from a template, remove sections that are not relevant. Keep your doc plan lean and mean. This will make for a faster review and approval process. People will feel happier about giving feedback on and signing off something that they understand. If there’s too much content, much of it irrelevant, people will lose track of, and lose confidence in, the bits that are important.

The resulting design, after you’ve incorporated people’s feedback, will be stronger.

What happens after you’ve drafted your doc plan?

After creating the first draft of the doc plan, the goal is to get other people to look at it and give you feedback. This feedback is essential, as it ensures that your understanding of the requirements is correct, and that the documentation that you’ll build will in fact satisfy the requirements.

I’ve found the following strategies useful:

  1. Walk through the doc plan with another tech writer, if possible.
  2. Walk through the doc plan with your stakeholders. I’ve found that an in-person walkthrough is very helpful, rather than immediately sending the doc plan out for review through email or other asynchronous means. During the walkthrough, you can iron out potential misunderstandings. People can ask you questions, and you can get immediate feedback from people who may not find the time to review the doc plan in detail.
  3. Incorporate any feedback from the walkthroughs.
  4. Send the doc plan out for review. Include the people who attended the in-person walkthroughs and all other relevant stakeholders. Set a deadline for review comments. A week is usually a good amount of time.
  5. Incorporate feedback from the review.
  6. Send the updated doc plan out again, and let people know you’re asking for approval. Give a deadline for the approval.
  7. Prod people until you have the approval you need.

Now you can start the most exciting phase of all: creating or updating the documentation!

Do you need to keep your doc plan up to date after the documentation is published?

After you’ve published the documentation, do you need to ensure that your doc plan stays in line with further updates? The answer depends on the processes in your specific business environment, but in general I’d say no. A doc plan does have value after the updates are done and dusted, as it shows the reason for the update and the overall design. In most situations, however, a doc plan is an artefact of the consultation, design, and review period of the documentation update. There’s no need to continue updating the plan after the documentation is published. The documentation site itself is the source of truth for current information about the documentation design.

Examples

Here are a few examples of doc plans provided by various people or groups:

Any more?

Do you have any examples of, or templates for, doc plans?

Related posts

Since publishing this post, I’ve written a couple of related posts:

Online class on technical writing principles

Google has published a few technical writing classes, which are available for people to attend and/or teach. I’ll be running one of the classes next week, at a time that’s convenient for the Asia-Pacific (APAC) region. If you’re an engineer or software developer who wants to improve your technical writing skills, then this course is designed for you. The course is also useful for technical writers and others who want to brush up their tech writing skills and/or tech the class at a future date.

The dates and times of all upcoming classes are published on the Google Developers Technical Writing site. The classes are run by various people, including Googlers and others.

Here are the details of the class that I’m running:

Class title: Technical Writing One
Date: Tuesday, January 12, 2021
Time: 8:30am – 11:00am IST (India Standard Time: UTC +5.30)
11:00am – 13:30pm SGT (Singapore Time: UTC +8)
14:00pm – 16:30pm AEDT (Australian Eastern Daylight Time: UTC +11)
Meeting link: Click to join class
Class format: Instructor led, online, free of charge. Participants work with partners (online) on the class exercises.
Prework: Read the pre-class material.

The Tech Writing One course was developed by technical writers at Google to train engineers and others in the principles of effective technical writing. It’s fun and interactive. The combination of pre-class reading followed by in-class exercises and discussions works well to help the participants retain what they’ve learned.

To join the class, click the above link at the time of the class. I hope to see you there! If you’d like to let me know you’re coming, feel free to add a comment to this blog post.

Soothing Musings: A new way of communicating

Soothing Musings with Sarah is a new way of communicating for me. Using a blend of beauty, information, and story-telling, my goal is to share a sense of calm in a few short minutes. This post describes where the idea came from and introduces the latest musing, called The Humble Mushroom. I hope you enjoy the post and the musing.

It all started from a realisation that walking in the Australian bush is, for me, a very soothing experience. I see the creatures carrying on their lives, short though those lives may be, as if there’s no need to worry about tomorrow. Birds and reptiles and animals, wild and beautiful, go about their business around me, accepting me as part of their world.

Every little sound is an indication of life. It’s a possum nibbling a leaf, or a parrot gnawing at a seed pod, or a branch rubbing against a tree trunk. Swamp wallabies bound-pound away then turn to examine me, ears and paws raised. An echidna hides its nose under a bush, convinced I can’t see the rest of its body, then peers out when I’ve been quiet for a couple of minutes and bumbles over to investigate my feet. A lace monitor lizard, longer than I am tall, waddles across my path then climbs a tree, tasting the air with flickering tongue.

In the early morning, all the creatures are out and about. In the middle of the hot day, the bush is quiet while everyone rests. When rain threatens, the cockatoos scold the universe with glee. Day turns to night, ushering in the Tawny Frogmouths and the shy bandicoots.

Life goes on. For me, it’s the comfort of the inevitable.

I wanted to find a way to capture and share the feeling of calm that I get as soon as I walk onto a bush path. One day, someone asked me to put together a lightning talk. on a topic of my choice. I thought, perhaps I could do a talk that was short on words and high in atmosphere. A soupçon of information, some beautiful images, and a ton of calm.

And thus Soothing Musings with Sarah was born. By design, each musing is just a few minutes long.

The humble mushroom, with music by Philip Horwitz

Now, I’m delighted to share the latest musing, The humble mushroom. This musing includes a gorgeous musical interlude by Philip Horwitz.

Over the course of a few months recently, I wandered through the forests and woodlands near my home, eyes on the undergrowth, looking for fungus. I was amazed at how many different kinds of mushrooms I found and how beautiful they are. All the photos in The humble mushroom are from a tiny area of Australia.

Click the image below, sit back, listen to some stories about mushrooms, then relax into the musical interlude.

For those who want to experiment

Would you like to put something similar together? This communication style may even be useful for some types of technical documentation. I recently wrote some guidelines on how to record yourself in a webcam view and show a presentation at the same time.

Top tip for breaking writer’s block

My top tip for getting out of writer’s block is: Move to a different medium, temporarily. Yesterday I was struggling to get started with some writing, and I remembered that this strategy often works for me. So I tried it. It worked again!

By “moving to a different medium”, I mean opening a text editor and jotting my thoughts there, or writing on a scratch pad, or simply opening a page that is completely separated from the work that I’m trying to complete.

When I’m trying to write something, there are two decisions I need to make:

  • What do I want to say?
  • Where should I put it?

Sometimes the two decisions are so intertwined that my brain gets in a loop. I start writing, then I think, “Wait, this shouldn’t go here.” So I delete what I’ve written. But then I realise that I do need to write it, and start again, and … loop. Then I spend time trying to figure out where the content should go, which makes me lose my thread of thought and lose impetus.

This destructive loop can happen in any type of writing. Most recently, it happened to me when I was providing detailed feedback in a doc review. I wanted to help the author with the syntax and correctness of the content, but the work also needed higher-level input on the structure of the page as a whole and its location in the doc set. I started putting my feedback on the page itself, but some of the feedback was too high level to belong on the page, or so I thought. So I removed what I’d written. But then there was nowhere to put that feedback, and I lost time trying to figure out how to give the feedback rather than focusing on what the feedback actually should be.

I was stuck. I went for a walk to clear my head. In the middle of my walk, I remembered what’s worked before! I moved out of the doc review tool into a text editor and jotted down my feedback as it came to me, without trying to decide where it belonged. When I’d finished, it was easy to slot the pieces of feedback into the right place.

This type of writer’s block can happen when you’re writing a book (“should this content be in the book, or is it more like plot and character notes for me, or should it be in the blurb?”) or a technical document (“does this content belong in this doc or another doc, or should I split the doc, or does it belong in a blog post?”) and so on..

Moving to a different format or medium gives my brain the freedom to write what I need to say. After that, it’s relatively easy to decide where the content should go.

Live streaming with StreamYard to record presentation and webcam view

I’ve recently started a YouTube channel called Soothing Musings with Sarah. I’ll tell you a bit about the channel itself later. First, though, I want to share what I learned about how to record a presentation alongside a webcam view of myself. After quite a bit of investigation, I found that the best combination of services for my needs is StreamYard, Google Slides, and YouTube.

For my video format, I wanted to include a mini window showing myself talking. I therefore needed an app that would record a webcam view. Alongside the talking me, I wanted a main window showing pictures of the thing I was talking about. For the main window, I decided a slide deck would be best, so that I could include text as well as photos. So, I needed an app that would record a slide presentation, as well as the mini window of me as presenter.

Here’s the end result:

I already had a Gmail account, which gives me access to Google Slides for presentations, and YouTube for sharing videos.

Getting started with Google Slides and YouTube

You can get help from the Google documentation on how to set up an account. You can use the same account for Gmail, Google Slides, and YouTube. There’s also information on how to create presentations with Google Slides.

Setting up a named YouTube channel

When you set up a YouTube account, you automatically get a YouTube channel that has the same name as your account. For my videos, I wanted a channel with a specific name: Soothing Musings with Sarah. YouTube calls a named channel a brand account (or sometimes just an account). A brand account doesn’t need to be a business account.

The YouTube docs describe how to set up a named channel. One thing to note is that there may be a 24-hour delay before your new named channel is available. I found there was no delay for my default YouTube channel, but the delay did occur for the named channel (brand account) which I created.

StreamYard for recording of presentation and webcam view

StreamYard gives you a browser-based streaming studio. I’m using Chrome as my browser. StreamYard works by streaming your recorded video directly to YouTube. All you need to do is set up your screen layout and other options in StreamYard, then record the session. As soon as you finish the session, you can watch your video on your YouTube channel. StreamYard gives you a link to the video on YouTube, which you can find on the StreamYard dashboard.

After you finish recording your video on StreamYard, YouTube still needs to complete some post-processing, which can take a few hours. When that’s done, your video becomes visible in the list of videos in your YouTube channel. That’s also when you can set the video thumbnail and download the video. Note that you can view the video on YouTube immediately after finishing the session on StreamYard, even before YouTube’s post-processing is finished.

Connecting StreamYard to YouTube

Here’s how to connect StreamYard to your YouTube channel:

  1. Sign up for a StreamYard account. StreamYard offers free and paid plans.
  2. In StreamYard, go to the destinations page. As you can see in this screenshot, I currently have two destinations set up in Streamyard: one for my default YouTube account, and one for my brand account. Your destinations page is probably empty at this point:
  3. Click Add a Destination.
  4. On the next page, click YouTube Channel:
  5. Follow the prompts to sign in to Google and to choose your account or brand account. Make sure you use the email address that you used to set up your YouTube channel.

When that’s all done, you’re ready to create your first recording, which StreamYard calls a broadcast.

Recording your session on StreamYard

The following steps include some tips that I gleaned while experimenting with StreamYard. They may not all apply to you, but they’ll at least help you get started.

  1. Get ready to be filmed. 🙂 Brush your hair, arrange your collar, do whatever you need to do to make yourself feel comfortable. Of course, you can choose not to include a webcam view in the recording. In that case, as you were.
  2. Go to the StreamYard broadcasts page and click Create a Broadcast:
  3. If StreamYard prompts you with a dialog window named Broadcast to, choose the YouTube channel that you want as the destination for your video recording.
  4. Set the title, description, and privacy for your video. I like to set the video to private at first, so that I can review it before the general public can see it:
  5. Click Create Broadcast.
  6. Check the view from your camera and the sound from your mic, as prompted by StreamYard.
  7. Set a display name. This is the text that appears on the bottom left of the webcam view. Looking at the video at the top of this post, you can see that my display name is Sarah Maddox, and it shows up as white text on an indigo background.
  8. This is when you enter the StreamYard studio. It looks like this:
  9. Take some time to examine the options, in particular the various settings available in the strip on the right-hand side of the studio. In the above screenshot, I’ve selected the Brand option, which is where you can set your brand colour etc. Some of the options are available in the paid plans only. For my brand colour, I chose indigo, which is why my display name has an indigo background. You can find some good colours on the material design website.
  10. If you want a recording of yourself to be part of the video, click the box with the webcam view near the bottom left of the studio page. That’s the box that shows a moving picture of you. By clicking the box, you add the webcam view to the video.
  11. Check the angle of your video camera, and make sure the webcam shows just what you want it to show.
  12. Now it’s time to set up the layout of your video. Click one of the layouts that appear in a row like this:

    I like the layout that shows 2 people on the left plus the presentation on the right. That’s the one highlighted in the above screenshot. Even though I’m showing only one person (that is, one webcam view) I like the sizing ratios in this layout.
  13. Move over to your Google Slides deck, and click Present then Presenter view, so that you can use the presenter view window to drive the presentation:

  14. You’ll see a presenter view window that looks something like this:
  15. In StreamYard, click the Share Screen, option, which appears at the bottom of the StreamYard studio:

  16. Choose the option to share the Chrome tab and select the presenter view for your presentation:

  17. Bring the presenter view window for your presentation to the fore, and drag the presenter view window to a convenient position, so that it doesn’t cover any bits of the StreamYard screen that you want to see while presenting. In particular, make sure you can see the “Go Live” button. The “End Broadcast” button will appear in the same place when you’re actually broadcasting, and you’ll want to find that easily.
  18. Now it’s time to start the recording. In StreamYard, click Go Live at the top right of the studio window:

  19. Click Go Live again to confirm that you’re ready. This starts the streaming to YouTube. (It’s OK! If you’ve set the privacy option to private, no-one but you can see the video while you’re streaming or even when you’ve finished.)
  20. Press Alt+Tab (or Cmd+Tab) to bring the presenter view to the fore again.
  21. Go for it! Have your say and show your slides.
  22. When you’re ready to stop recording, click End Broadcast at top right of the StreamYard studio:

  23. Click End Broadcast again to confirm. Wait a second or so until StreamYard lets you know that it’s closed the stream.
  24. Take a look at your video! In StreamYard, you can click Links at top right of the studio window, then click View on YouTube:

  25. Alternatively, you can click Return to Dashboard and see your list of recorded videos on the Past Broadcasts tab:
  26. Click the three dots next to each recording to see various options, including the option to view the video on YouTube.

You can also see the video directly from YouTube. In your channel, Click Your videos then select Live streams from the dropdown list:

  • After some hours, the video appears in the Uploads list too.
  • In YouTube Studio, the recording appears on the Live tab.
  • Note that the Download link for the video in YouTube Studio doesn’t work immediately — it’s greyed out. It took a few hours for me before the link became active.

Other hints:

  • While recording in StreamYard, you can remove the webcam window but retain audio: Click the layout option that shows just the full screen. You can then put the webcam back again by choosing your original layout option.
  • The StreamYard docs are excellent, including a good set of FAQ.

Other services that I tried

I tried a few other services to get the layout that I needed. When live streaming with YouTube Live, I couldn’t share my screen. ScreenCastify is very easy to use and produces nice results, but I couldn’t get the onscreen camera box (webcam view) to appear when in presenter mode with Google Slides. 

My channel: Soothing Musings with Sarah

My YouTube channel is a new type of communication for me. I’m attempting to use voice mixed with beautiful pictures of nature, plus a soupçon of information, to convey a sense of calm. Hence, Soothing Musings with Sarah. At this point, the channel has a couple of videos streamed via StreamYard. I’m experimenting as I go. There’ll probably be more to come.

If you’re investigating how to record a video with a camera view and a slide deck, I hope you find this post useful.

%d bloggers like this: