Community Discourse Docs Quick Start Guide

Migrating Existing Documentation

Preparing for Document Migration

Prior to migrating information from the Ubuntu Wiki, it’s important to ask a few key questions:

Is the information accurate?

Is the information current?

Is the information helpful to the community?

If the answer to all these questions is YES, then it may be a good candidate for migration!

Creating the Topic

Migrating documentation from the Ubuntu Wiki is a fairly simple and straightforward process. However, a working knowledge of technical writing and Markdown, the markup language Discourse topics are written in, will be helpful.

Step 1) Identify the document in need of migration. Be sure to check the Documentation section in Discourse to see if it has already been moved.

Step 2) Create a new topic in the appropriate Documentation section. Add a clear title and make sure to use appropriate tags.

Step 3) Copy the document text into the text field and make any edits or formatting adjustments. Discourse will show a preview of the topic.

Step 4) Before you publish, it’s important to perform a thorough review of your topic.

Review and Publish

When migrating existing documentation, always be sure to check for and correct the following:

  • Spelling or grammatical errors
  • Formatting issues
  • Broken or outdated links
  • Graphics that are unclear or illegible

Once the topic is free of issues, it can be published to the Discourse.

Cleanup

Once a topic has been posted, you can put in a Wiki Topic Removal Request where an editor will review the document, make suggestions or changes, and finally decommission the original wiki source.


Writing new Documentation

For those looking to write new documentation, the process is also quite simple.

First, it’s important to verify that the work doesn’t already exist in the Ubuntu Discourse or Ubuntu Wiki.

Finding your style

For our documentation, we prefer to use the Diátaxis framework. - This method of structuring technical documentation relies on sorting them into 4 distinct groups, each with its own set of goals and intentions.

You can read about each of the types by clicking on them below:

Topic Drafting

Once you have a topic in mind and clear focus on which of the 4 styles it belongs, you can begin your draft. Some people opt to draft their documentation in another source such as Google Docs or a GitHub repository before formally posting it on Discourse.

As mentioned in the migration section, all Discourse topics are written in Markdown, an easy to learn markup language.

Creating the Topic

Once your draft is ready for publication, you can follow these steps:

Step 1) Create a new topic in the appropriate Documentation section. Add a clear title and make sure to use appropriate tags.

Step 2) Enter your topic text into the text field and make any edits or formatting adjustments. Discourse will show a preview of the topic.

Step 3) Before you publish, it’s important to perform a thorough review of your topic.

Review and Publish

When creating new documentation, always be sure to check for and correct the following:

  • Spelling or grammatical errors
  • Formatting issues
  • Broken or outdated links
  • Graphics that are unclear or illegible

Once the topic is free of issues, it can be published to the Discourse.


For any questions regarding Community Documentation, please feel free to ask them in the #ubuntu-doc or #ubuntu-community-team channels on IRC.

2 Likes