Merge pull request #108 from camerons/howto2md

The changes to the MD format work well and the removal of the AsciiDoc table makes this template consistent with our direction for templates. Nice work @camerons
thegooddocsproject · Mar 1, 2020 · 24226fa · 24226fa
2 parents 994bb19 + 6bab2f1
commit 24226fa
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 59 deletions.
diff --git a/how-to/about-howto.md b/how-to/about-howto.md
@@ -49,14 +49,7 @@ Make sure you meet the following prerequisites before following the steps:
 
 ### About the "Step by step guide" sections
 
-When you are explaining steps in a process, it can often be useful to include a screenshot for each part of the process.
-What can often happen is that when you try to insert a graphic or screenshot into the flow of the procedure, it breaks the procedural content up and makes the instructions difficult to read.
-
-In the `template-howto.adoc` file, you'll notice the tabular step format in the Step-by-step section of the template.
-The tabular format allows you to add in your procedural steps right next to the screenshot and reference steps with call-outs.
-
-If you procedural steps do not require screenshots, then you can default to an ordered list.
-You can also get this structure in Markdown, but you may need to resort to HTML tables. For Markdown, keep the list as an Ordered list.
+..
 
 ## How-to Article Examples
 

diff --git a/how-to/template-howto.adoc b/how-to/template-howto.adoc
diff --git a/how-to/template-howto.md b/how-to/template-howto.md
@@ -0,0 +1,48 @@
+<!-- Copy this Template. -->
+<!-- Describe the title of your article by replacing "How-to Template" with the page name you want to publish to. -->
+# How-to template
+
+## Overview
+
+Summarise what this how-to article is about in a sentence or two.
+
+**Keywords:** Optionally add comma-separated keywords.
+
+## Before you start
+<!-- Delete this section if your readers can dive straight into the lesson without requiring any prerequisite knowledge. -->
+Make sure you meet the following prerequisites before starting the how-to steps:
+
+* Prerequisite one
+* Prerequisite two
+* etc
+
+## Step-by-step guide
+
+### Step 1: Optional: Title for step - image or screenshot
+
+<!-- When an image, such as a screenshot, is quicker to interpret than descriptive text, put the screenshot first, otherwise lead with the text. -->
+
+![alt text](https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg "Image title which describes image.")
+
+Brief instructions explaining how to interpret the image.
+
+### Step 2: Optional: Title for step - ordered list
+
+Lead-in sentence for an ordered list:
+
+1. Substep A
+1. Substep B
+1. Substep C
+
+### Step 3: Optional: Title for step - code snippet
+
+Lead in sentence explaining the code snippet. E.g.: 
+
+Run the `apt` command to install the Asciidoctor package and check the version.
+
+```
+$ sudo apt install asciidoctor
+
+$ asciidoctor --version
+Asciidoctor 1.5.6.2 [https://asciidoctor.org]
+```