At this point, you should know what content exists and what still needs to be written. Let's get writing!

Get ready to write

Follow Markdown guidelines and best practices to ensure your team is clear about the organization and governance of your content. When you're dealing with a large quantity of content that you need to create or reorganize, try asking these questions:

• Who is the anticipated audience for this information? For example, new hires or senior staff looking for guidance?
• What are the current pain points with the content?
• Can individual sections of each document stand alone? (Can you break documents down into smaller chunks for quicker reference?)

Suggested categories

These categories work well for organizing most software documentation logically:

• Getting started: Explain how to get started with your project's core use case.
• Overview: A landing and marketing page about your project.
• Concepts: Overview, conceptual, or narrative-type topics.
• Tutorials: Task-oriented or step-based topics.
• Support: Information about troubleshooting common problems and who to contact with questions.
• ReferenceAPI calls and other information people need to work with your project.
• Case studies: Examples of your project in action.
• Release notes: Brief summaries of the features and updates accompanying a release.

Getting started

Getting started pages assist developers and users in getting up-and-running. Getting started pages are created in series, with large tasks broken down into sub-tasks. Avoid creating more than one getting started series for each project. The getting started series should include:

• A getting started overview page, including an introduction to the steps ahead and prerequisites to get them done. If the steps are quick enough, everything can be on the same page. Otherwise, break them up.
• Required access, applications, and dependencies.
• Information about IDE(s), if applicable.
• A page for every significant task, broken down into sub-tasks.

Concept

Concept pages provide short, high-level information:

• Why should the developer or user care about this information? (What's in it for me?)
• How does it relate to what they're doing?
• Is there anything they need to be aware of before starting?
• Does it impact anything else?
• What additional pages are relevant?

Reference

Use reference topics to provide technical information and definitions that support a user in performing a task. A glossary topic lists words and acronyms, but a reference topic lists project specifications, parameters, methods, functions, and other information that needs to be referenced. Reference topics usually contain tables with names, descriptions, and code examples.

Support and troubleshooting

Create an email distribution list for receiving support questions. Include that distribution list, instructions on creating a support ticket, and any other contact information you want your users to know. Ensure this information matches the info on your project overview page.

For the troubleshooting section, include:

• The background or cause.
• How to determine.
• The solutions or workaround (if a solution isn't available, include a workaround).

Case studies

Adding case studies to content gives your users a feel for how people use your project, and how they can potentially use it. Consider these headings in the template when putting together your case studies (or even better, have your clients help you):

• Problem statement.
• Challenges and opportunities.
• How did you leverage the platform well?
• What worked well?
• What could use improvements?
• Technical contact's email address (or distribution list).

Release notes

Release notes must accompany an application upgrade or release.

Changelogs

A changelog is a release-by-release listing of what's been added, changed, or removed in each area of your project. It's often more granular than release notes.

About FAQs

Avoid creating frequently asked question (FAQ) topics. Questions are frequently asked for a short time and are difficult to maintain.

If an FAQ page is necessary, limit it to one page for each project and limit the number of questions to 10. Frequently check the page for required updates and grooming.

Next step

Test your documentation