Skip to content

Instantly share code, notes, and snippets.

@edburns

edburns/ssdocschecklist.md

Last active November 18, 2021 17:56
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save edburns/f87a069f2fa88ce33ea7fd6bbd9c8398 to your computer and use it in GitHub Desktop.
Save edburns/f87a069f2fa88ce33ea7fd6bbd9c8398 to your computer and use it in GitHub Desktop.
Download ZIP
Self Service Docs Checklist
Raw
ssdocschecklist.md

If possible to answer in this checklist, correct answers are in bold.

  • Does the content conform to a specific topic type?

  • If no, evaluate the content to select the best fit and re-work it to make it a better fit for that topic type. Then go to the next item.

  • If yes, which topic type?

  • Does that topic type have a template? Known templates include

  • Overview

  • Quickstart

  • ARM template quickstart template

  • Tutorial

  • If that topic type does not have a template look for existing examples for that topic type.

HOW TO GUIDES are:

  • Procedural articles that show the customer how to complete a task. To provide the steps for completing a task. To help customers complete tasks in their own environment. How-to guides differ from tutorials in that they can include optional information, explanations, and information to help inform decisions. "task" can be somewhat high-level and include multiple small sub-tasks from which the user can select and use, not necessarily in any order. For example, the high-level task might be "configure", with subsections on configuring this, that, and the other thing, both this way and that way.

  • Picture a how to as the gap that couldn't be filled between an overview, quickstart, and tutorial. Most of my personal usage or what I've seen others do is use it for loose procedurals that don't conform to the other requirements.....too long to be considered a quickstart - doesn't show a primary implementation path......you can do this, or this, or this, etc

  • Does the content require changes in the toc.yml or index.yml?

  • If so, unless it's unavoidable, make sure your TOC labels never wrap to a second line.

  • Does the topic, and every section within the topic, start with a concise statement of what the reader can expect? Tell them what you're going to tell them. yes

  • Does every hyperlink in the content follow the formula: context, then link? Unless you want to say something more specific, you can fall back on the template "For more information, see " where the link text is the title/heading you see when you follow the link. yes

  • Does every section heading use sentence capitalization? yes

  • If the content has a Prerequisites section, is it the first section after the intro section? Is the Prerequisites just a list with no intro sentence? yes

  • Does every list have a short intro sentence? The idea here is that you are clearly labeling the intent of the list, which assists scanability. yes

  • Is any text that is from the user interface being read by the reader in bold? yes

  • Are any filenames, extensions, paths, etc in italics? yes

  • Have you removed all occurrences of log in, login, log into, log on, logon, log onto, log off, log out, logout, or a similar term unless it appears in the UI (and you're writing instructions) and replaced it with sign in, sign out, or connect? yes

  • Is each list that is a sequence of steps a numbered list? yes But it is also important to consider that this guidance applies to short lists. Some people have a tendency to turn a long procedure into a giant numbered lists where some items contain sublists etc. In this case, the top level should just be paragraphs and/or sections, and you don't need the numbering.

  • Is each list that is a set of alternatives a bullet list? yes

  • Does the content direct the reader to perform the steps in some other content, which resides on the other side of a hyperlink?

  • If yes, is this absolutely necessary? Ideally this patterns should be avoided, but our content often seems to require this pattern.

  • If it really is absolutely necessary to direct the reader to perform the steps in some other content, make it extremely clear that the reader is expected to return to this content after performing the steps in the other content. If the reader must collect information while performing the steps in the other content, be extremely clear about what information they need to gather.

  • Do you use the word "click" anywhere in the content? no "Click" implies a mouse. Many readers are using a touch device. Use "select" instead. For the rules on "click" see its entry in the style guide.

  • Do you use the word "hit" anywhere in the content? no Same reason as for "click".

  • If the content includes conceptual art, did you remove the grey border? yes

  • Are all the arguments to all the CLI commands in the correct order as shown in the guide? yes

Related Reading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment