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.

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:

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.

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.

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.

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) Replace any content placeholders with the appropriate content. Search for "REPLACE WITH".
# 2) 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.

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 on 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.

For Presidium to support the functionality it has built on top of Hugo there are some performance considerations to take into account so that build times can remain reasonable. Below are some steps that can be taken to help with overall build performance:

• Keep total markdown content to 50MB or less, this should result in a build time of around one minute, but this cannot be guaranteed due to other factors

• Content spread across multiple files is more performant that having fewer files with more content

• Less content per markdown file is encouraged, this also supports Presidium’s philosophy of small micro-articles

• While project dependent multiple directories with single a _index.md file has better build performance