Key Concepts

Presidium is more than a framework for producing documentation. It asks you to think about, structure, author, and publish content based on sensible best practices so you can write effective documentation, rather than producing documentation for documentation’s sake.

Supporting Learning Objectives & Efficiency

Presidium recommends creating small micro-articles that convey enough information to fulfill a learning objective. Small articles are advantageous because they:

• Usually only require a single author
• Force the author to focus on effectively describing a single concept
• Enable authors to quickly add documentation while also working on a product or service.

Using this method, creating high quality content is part of the engineering process, not a deferred or protracted task.

Categorization

Often, either only a few people hold all the critical business and technical knowledge or information is spread across documents without organization or cohesion. Presidium suggests a way to categorize information that helps the writer compartmentalize and categorize knowledge, leading to more cohesive and logical documentation.

Overview & Key Concepts

Almost any knowledge base requires an overview to orient the reader in the correct domain. The Overview section should support and lead to a discussion of key concepts that prime the reader to use the rest of the content. These two sections are naturally presented first, and one should follow the another.

Prerequisites & Getting Started

For software projects, APIs, and similar documentation, most readers will require some initial preparation. This may include installing libraries or binaries and reading information before proceeding.

The Prerequisites section should support the information in Getting Started. The Getting Started section should be a quick deep-dive than enables a user to get from nowhere to running in minutes.

Best Practices

The Best Practices section should contain the ideal path to follow to get the most out of your product or service and reduce the potential of encountering problems. They can be a combination of anecdotal knowledge, RFCs, white papers etc.

Reference

References should enhance or support the information in other sections (for example, imported API documentation, deep-dives beyond the needs of most readers, etc.)

Recipes

Recipes are clear sets of steps that explain how to do something useful or unusual with your product or service.

Glossary

Glossary entries are bite-sized pieces of information that explain a concept, resolve jargon, or list synonyms for a particular term. Because all content in the Glossary can be used for automatic tooltip generation, a good rule of thumb is to make sure a glossary entry can be condensed into a tooltip without being verbose or introducing confusion.

More

Tools, Uses Cases, Updates, and Support are other sections you can use. You can also define your own sections in Presidium.

Structure

For simplicity and transparency, the menu structure and associated directory structure are the same.

Behavior

A significant feature of the menu is its tree structure: each section or subsection is a node and content traverses from each node through its children. In Presidium, the node name or title becomes the main header of the page. Everything outside of that sub-tree is not presented on the page. In this example, the user has clicked Content Structure. Everything under that section is displayed:

Note the URL: /recipes/content-structure/. When you click on a section or subsection title, the url is included in the path. If you click on an article in a subsection (for example, Article Concatenation), the URL changes to /recipes/content-structure/#article-concatenation.

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.

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

• Default Template
• Design Template
• Onboarding Template

The following workflow is recommended for authoring content using Presidium.

Identify the Author

Whether you’re creating a single article or an entire section, make sure to include the author tag in the front matter.

Work Locally

Presidium encourages you to write and review documentation on your local machine, rather than making changes directly on Github. The advantages to this workflow are:

• Changes are immediately viewable
• You can leverage Presidium’s validation tools
• Git commit history will have less noise

Protect Master

If you own the documentation project, make sure you prevent others from making commits or pushing to the Master branch. You will be publishing from the Master branch, so you want to maintain its integrity.

Work On a Branch

If you’re adding new content, start out on a branch based off of develop.

Review

Changes should be submitted as Pull Requests. Review all changes and merge into your Develop branch, then tag the release as a release for verification.

Tag, Release & Publish

After you’ve finalized the new content, merge it into Master, tag it as a release, then publish to Github pages.

You should define the knowledge and skill set of your target audience before starting your documentation. You can then use this information to avoid wasting time explaining information your audience already knows.

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]

For each learning objective, you should:

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

Markdown is an ubiquitous, lighweight markup language known to almost any engineer. If you don’t know Markdown, it’s easy to learn. Presidium uses a version of Markdown known as Github Flavoured Markdown and leverages this ‘common tongue’ to enable multiple contributors to create documentation quickly without wasting time doing point & click styling or having to alter HTML and CSS.

Style Guides

For any documentation project, a Markdown style guide ensures that contributors write documentation that is consistent with your intended tone and layout.

Flexibility

If you need more flexibility than Markdown offers, you can also use HTML separately or mixed with Markdown content in articles.

Presidium is built on sound theoretical strategies for developing learning content and managing knowledge assets. The core of this approach is the development of specific focused micro-articles that explain individual concepts.

This splits the problem of content development into two parts:

1. Defining a site outline based on the concepts that must be documented and how they should be sequenced and presented.

2. Developing articles that each explain each concept, using a standard template to ensure consistency. Micro-articles break the documentation development and maintenance activities into manageable chunks that can be prioritized based on need. In many cases, it’s possible to write and review an article in under 20 minutes. See Writing Effective Articles

This Presidium documentation site not only explains the Presidium software but also includes best practice guidelines for writing your documentation.

Presidium is designed to make it easy to write and maintain your documentation. Instead of a monolithic document, Presidium manages a directory structure of micro-articles. The directory structure maps to the sections of your site, while the articles are joined together to build the content of each section. You can create a directory to add new sections and sub-sections. Each section contains a sample article template you can use as a starting point when creating new content. This site explains other best practices for writing articles.

If you know how to maintain a codebase in a Github repository, you already know how to maintain Presidium documentation. You can use your team’s current Github workflow to manage the approval and publication process and use Github’s features to handle merge conflicts and other issues, just as you do for your source code. You can easily modify the suggested site structure and behavior. Most teams only need to remove a few sections that are not relevant to their project. Presidium has several configurable features that can be enabled as needed.