doc-template.md

title	description	draft
Pantheon Documentation Template.	A short description of the doc.	true

This self-referencing document can be used as a starting point to write your own new doc for Pantheon. Start with an overview of the topic, which may include a summary of what will be accomplished after following the instructions.

Note

For optimal use of this document, consider viewing the markdown file and rendered page in Sculpin side-by-side. Any important points the customer needs to be made aware of can be put in a note like this.

Before You Begin

Here's a list of prerequisites or technical requirements a user must have or understand before starting the task. This is a good place to use:

• A bulleted list
• Links to local software needed first
• Links to any Pantheon docs readers should read or comprehend the concepts of before starting this one.

The steps of your guide should be broken into sections. Particularly long sections should be broken further into subsections. Read on for examples.

First Major Step

Because this section will have its own subsections, a line or two to briefly describe the goal of this main section should go here.

First Subsection Step

1. You shouldn't need to drill down any further than this. You'll also notice no need to preface the section, we can begin with instructions.

2. For sections with several steps, be sure to use numbered lists. Notice how this list has two spaces before instruction. That's to keep steps arranged with 4-space soft tabs. More on this further down.

3. To show you how we're spacing ordered steps, here's the previous two steps in code block form.

   1.  You shouldn't need to drill down any further than this. You'll also notice no need to preface the section, we can begin with instructions.
   
   2.  For sections with several steps, be sure to use numbered lists. Notice how this list has two spaces before instruction. That's to keep steps arranged with 4-space soft tabs. More on this further down.
   

   The codeblock above was created using indentation. While this is quick and easy, we have no control over the syntax highlighting, and our example doesn't look very good.

4. Let's try again using a code fence.

   1.  You shouldn't need to drill down any further than this. You'll also notice no need to preface the section, we can begin with instructions.
   
   2.  For sections with several steps, be sure to use numbered lists. Notice how this list has two spaces before instruction. That's to keep steps arranged with 4-space soft tabs. More on this further down.

   This time we've blocked our code and specified the contents as Markdown with ``` markdown.

Now that we've successfully completed this section, we can move on. By indenting the steps above properly, this line will be aligned further left, indicating a break from the steps.

Our Second Subsection

1. This section may reference concepts already described above easily in each step with in-line code snippets.

2. If new concepts or ideas are introduced, we'll use bold to emphasize it.

3. Finally, let's provide another code block example, with a more interesting syntax to highlight.

   $ git clone git@github.com:pantheon-systems/documentation.git
   Cloning into 'documentation'...
   remote: Counting objects: 41601, done.
   remote: Compressing objects: 100% (137/137), done.
   remote: Total 41601 (delta 83), reused 0 (delta 0), pack-reused 41463
   Receiving objects: 100% (41601/41601), 112.21 MiB | 5.91 MiB/s, done.
   Resolving deltas: 100% (31995/31995), done.
   $ cd documentation/
   $ git checkout -b update-template
   Switched to a new branch 'update-template'

Notice that in this example we've left a small prompt symbol ($) to indicate which lines are commands entered by the reader, and which are output from those commands.

Second Major Step

If you're looking at this document as generated by Sculpin, you'll notice by now that the table of contents (TOC) has expanded to show all the previous subtopics. As we move further down it will retract the sections of First Major Step, and highlight the current section. If you need to refer the reader to another section in the guide you can use an anchor link as we just did.

Now let's look at some of the commonly used Markdown syntax in the docs.

Images

Images are a great way to show what the user should be seeing in a graphic user interface (GUI) environment, like the WordPress Admin Dashboard:

Warning

Images of terminal output is frowned upon. When small changes are required to comply with software updates, replacing a few characters is much easier than generating a new screenshot.

Other considerations

• Avoid be verbs
• Avoid colloquialisms and personal opinions, feelings, or anecdotes.
• Only assume as much knowledge from the reader as specified in Before You Begin. Otherwise explain everything.
• Notice the draft: true line in this template's header? If keeps this page from being visible in the live site. Be sure to remove it from your doc.

##See Also

If you can, end your doc with links to external resources that can be used to improve the reader's comprehension, or to guides on logical next steps in a common development workflow.

• An internal guide with a relative link
• An external guide with a full URL