Best Practices


No articles match the selected filter.

Plan Content Development

Before you write any content, spend some time anticipating what tasks you need to perform and make sure you have the time and resources to achieve your goals.

The following steps work for both small and large projects:

  1. Design the site structure
  2. Inventory existing content
  3. Plan the conversion of existing content into articles
  4. Map the planned articles to your structure
  5. Identify required new articles
  6. Repurpose existing content into articles
  7. Write new articles
  8. Proofread and edit
  9. Publish

Discussion

The most important planning task is identifying the scope of your documentation efforts and understanding the needs of your audience.

Presidium is pre-configured with a set of standard sections that are commonly used in software documentation. You can use this framework when starting to scope your project.


Design Documentation Structure

Before starting to write content, you should define the documentation structure to answer questions such as:

  • How many sections do I need?
  • What should each section cover?
  • Do some sections need sub-sections?

Answering these and other questions will help you scope the project and define the content that needs to be found or written.

Keep in mind that although you should decide on the structure of your site at the beginning, you might need to make changes as you gain a deeper understanding of the content. With Presidium, it’s easy to change the structure by moving articles.

The Presidium templates are pre-configured with a standard menu structure that you can use to start scoping your documentation. You can add new sections but in most cases, the standard sections will suffice.

The following table shows the pre-configured sections in the software documentation template:

Section Description
Overview A brief, business-level overview of the solution that includes the main benefits vs. alternative solutions.
Key Concepts Introductory descriptions of the solution’s key concepts, components, and structures that include roles and responsibilities for the component.
Prerequisites A summary of the required knowledge, skills, and software to successfully use the solution.
Getting Started Information on how to get started using the solution.
Best Practices The recommended approach for using the solution.
Reference Information on the technical content of the site. APIs, data structures, etc. Reference material should also include detailed descriptions of how to use each part of the solution, arranged by conceptual area.
Recipes A solution for a specific problem or a way to achieve a specific objective. Recipes are used to show a user how to do something.
Glossary A list of definitions for terms that have specific meanings in the solution documentation.
Use Cases Descriptions of how the solution’s components work together to enable commonly implemented scenarios. Use cases should include code examples.
Tools A list of tools and services that can be used with the solution.
Updates New releases, patches, or other announcements of interest to the user community.

Discussion

After you have identified the sections you want to use for your documentation, define and compile a list of the learning objectives for each section.


Define Learning Objectives

When defining learning objectives, think carefully about what it means to use your solution effectively by doing the following:

  1. Identify what your audience should know and be able to do after they have read the documentation.
  2. Use that information to create a list of learning objectives.

Just as stories are used to define software, learning objectives can be written using a standard template.

As a [user] of the [solution] I [know a specific piece of information] or can [perform a specific task]

Often, existing stories can be converted into learning objectives with little or no alteration:

  • As a first time user of Presidium I can easily download, install, and run the latest version.
  • As a Presidium user, I know the value of defining learning objectives for developing comprehensive content.

Clearly worded learning objectives enable you to focus the content on comprehensive and coherent goals. Learning objectives should be evident in the title and content of articles. Often, one learning objective corresponds to one content article.

Discussion

Define the knowledge and skill set of your target audience before starting your documentation. Use this information to avoid wasting time explaining information your audience already knows.

  • As a user of Presidium I already know how to use Github as a version control system.
  • As a user of Presidium, I know what Markdown is, I have used it before, and I know how to look up details about Markdown syntax I may not know.

Inventory Existing Content

When starting a new documentation project, you should first review and evaluate existing content. Content from multiple sources, such as those listed below, can be repurposed:

  • Existing software documentation
  • Wikis and message boards
  • Design documents
  • Work tickets (epics and stories, bugs)
  • API specifications
  • README files
  • Code comments and markup
  • Help files
  • Emails
  • Meeting notes
  • Project planning materials

Before starting:

  1. Compile a list of existing content sources.
  2. Identify how each item could be decomposed or converted into an article.
  3. Identify where these articles can fit in your documentation structure.

Discussion

If there is no existing documentation set, some areas will be well documented, while others will either be poorly defined or missing. Expect to find duplicate and outdated content. Maintain a list of the best documentation you find for any learning objective.


Use Article Templates

Presidium includes article templates for each of the pre-defined sections. Templates are text documents that contain instructions and Markdown which can be modified to meet your needs.

For example, here is the template for the Best Practices section:

```# Template Instructions
# ---------------------
# 1) Copy and rename this file remove the leading "_". For example: keep-it-simple.md.
# 2) Replace any content placeholders with the appropriate content. Search for "REPLACE WITH".
# 3) Delete this line and all lines above so that the front matter below is at the top of the file.
---
title: REPLACE WITH Best Practice Title
author: REPLACE WITH repository username
---

REPLACE WITH a summary paragraph of the recommended practice.

```python
    REPLACE WITH A code snippet, if required, that illustrates the recommended practice. Change the name of the language if needed. DELETE the entire section if not required.
```

# Discussion

REPLACE WITH a discussion of the recommended practice. Add subheadings, code snippets and tables as required.

# See Also

* [REPLACE WITH a link description](http://www.example.com)

Discussion

Templates encourage consistency and provide a simple checklist that an author can use for inspiration.


Writing Effective Articles

Anyone can write great articles if they follow a few simple style guidelines:

  • Make sure the title explains what the article is about. The title will be used to construct the navigation menu and will often be separated from the article body along side other article titles.
  • Make sure the title works its own and describes the essence of the article.
  • Keep titles simple and succinct without using humor or colloquialisms.
  • Have one author for every article. This enable authors to quickly add documentation while also working on a product or service.

Discussion

Articles should convey enough information to fulfill a learning objective.


© Copyright 2018 SPAN Digital

Generated on Nov 21, 2018