Related to #8 -- most of "Writing Docs" is done, but not all of it ye…

…t. Pushing now since it's already a lot of work.
impress-org · Jul 6, 2018 · d76509c · d76509c
1 parent 1e38cb1
commit d76509c
Show file tree

Hide file tree

Showing 10 changed files with 70 additions and 8 deletions.
diff --git a/documentation/assets/give-documentation-share-image.png b/documentation/assets/give-documentation-share-image.png
diff --git a/documentation/assets/writing-docs-addon-link-sidebar.png b/documentation/assets/writing-docs-addon-link-sidebar.png
diff --git a/documentation/assets/writing-docs-article-in-section-frontend.png b/documentation/assets/writing-docs-article-in-section-frontend.png
diff --git a/documentation/assets/writing-docs-page-attributes.png b/documentation/assets/writing-docs-page-attributes.png
diff --git a/documentation/assets/writing-docs-parent-doc-metabox.png b/documentation/assets/writing-docs-parent-doc-metabox.png
diff --git a/documentation/assets/writing-docs-sidebar-metabox.png b/documentation/assets/writing-docs-sidebar-metabox.png
diff --git a/documentation/assets/writing-docs-summary-frontend.png b/documentation/assets/writing-docs-summary-frontend.png
diff --git a/documentation/assets/writing-docs-summary.png b/documentation/assets/writing-docs-summary.png
diff --git a/documentation/assets/writing-docs-template.psd b/documentation/assets/writing-docs-template.psd
diff --git a/documentation/writing-docs.md b/documentation/writing-docs.md
@@ -1,10 +1,72 @@
 # Writing Online Docs
 
-* The Goal for All Docs
-* Composing Docs 
-    * Summary
-    * Parent Doc Metabox
-    * Field options
-    * Excerpt
-    * Featured Image
-    * Yoast Options
+Writing online documentation is a craft that takes experience and critical feedback. Being able to make technical things clear and understandable in a tone that is empowering for the reader can be challenging. 
+
+This article walks through how we approach writing online documentation for our products.
+
+## Goals for All Documentation Articles
+
+There are several important goals for every documentation article that we write. 
+
+1. Provide detail for all features of the product
+2. Answer any questions the reader might have related to the feature in question
+3. Provide context to how this feature relates to other features of the product or add-ons of the product
+4. Expand the content of our website to further encourage search engines to make our website the authority on all technical matters related to the product
+
+
+## Composing Docs
+All our docs are custom post types build specifically for online documentation purposes. Documentation is a major source of content that greatly improves the search index for our website. Hosting our documentation on our website also ensures that we can build the docs in any way we see fit.
+
+### Summary
+![Screenshot of the Summary metabox](assets/writing-docs-summary.png)
+
+The Summary is a quick overview of what the reader should expect to learn from reading this doc. In just 1-2 sentences, the reader should know quickly whether they will find the answer to their question in this doc or not.
+
+The Summary is presented at the very top of every doc in a distinct way to call attention to it.
+
+![The Summary at the top of a documentation article](assets/writing-docs-summary-frontend.png)
+
+### Sidebar Metaboxes
+When editing/writing a doc, there are several metaboxes found in the sidebar which are important and necessary to display the doc in the appropriate manner. 
+
+#### The Page Attributes Metabox
+
+![The "Page Attributes" metabox in our docs CPT](assets/writing-docs-page-attributes.png)
+
+The "Page Attributes" metabox is added by default in WordPress to any custom post type that is hierarchical (like "Pages", not like "Posts"). All our docs are hierarchical so that navigation as a reader is an intuitive as possible. The hierarchical navigation structure has clear SEO benefits [over other hosted docs solutions](https://freemius.com/blog/build-knowledge-base-documentation/#not-helpscout).
+
+Setting the correct "Parent" of the doc ensures that the navigation works as intended. 
+
+#### Documentation Sidebar
+
+![Documentation Sidebar metabox](assets/writing-docs-sidebar-metabox.png)
+
+When a documentation article is related to a specific add-on, we want readers to be able to navigate directly from the article to the Add-on product page. Setting this to "Yes" adds the link in the sidebar of the article, like so:
+
+![The add-on link in the documentation sidebar](assets/writing-docs-addon-link-sidebar.png)
+
+#### Parent Doc 
+
+![Parent Doc Metabox](assets/writing-docs-parent-doc-metabox.png)
+
+If the article you are writing has child-pages beneath it, it's important to set this option to "Yep". Child pages are output on the frontend near the top of the article in order to invite readers to dig deeper into the documentation. 
+
+When this option is set, the child-pages appear near the top of the article like so:
+![Screenshot of "Articles in this Section" under the Summary of a documentation article](assets/writing-docs-article-in-section-frontend.png)
+
+#### Featured Image
+
+While featured images are very important for SEO and social sharing purposes, they are not strictly necessary for all documentation articles. If a featured image is not selected for an article, there is a default image:
+
+![Default Documentation Featured Image](assets/give-documentation-share-image.png)
+
+Generally speaking, if the article is related to an add-on, you should choose the add-on product tile image for the featured image. Otherwise, the default image (meaning, no featured image selected) works just fine.
+
+### Field options
+
+
+### Excerpt
+
+
+### Yoast Options
+