Contribute to the Server Guide

Server Guide
1

Contributing to documentation can be a fantastic way to get started as a contributor to open source projects, no matter your level of experience!

The Ubuntu Server Guide is a collaborative effort between Canonical and the Ubuntu community, and ALL types of contributions are welcome; whether you’re new to Ubuntu Server and found something confusing, or you’ve been using Ubuntu Server for a while and want to create guides to help others.

How is the Server Guide created?

The Ubuntu Server documentation pages are generated from special forum posts in the discourse.ubuntu.com Server category.

These posts are published as wiki topics, meaning they can be edited by anyone with enough reputation on the discourse. But you don’t need edit rights to be able to contribute, and your trust level increases just by participating in the community!

How does contributing work?

If you spot something in the documentation that could be improved (or needs to be corrected), the best way to contribute is to report it to us so we can fix it! This could include (but isn’t limited to):

  • Spelling/grammar errors
  • Broken links
  • Code snippets that don’t work as expected
  • Things you didn’t understand or that could be explained more clearly

At the bottom of every page in the documentation, you will find a link that says “Help improve this document in the forum”. Clicking this link will take you to the corresponding Discourse post.

Underneath each post you may find a thread, or several threads, of discussion about the topic. You can add your comment by clicking “reply” on the original post. If there is already a discussion happening about the thing you want to report, you can also jump into the conversation by replying to one of the existing comments.

I want to contribute new pages

Firstly, thank you!

Documentation at Canonical is undergoing a transformation, which includes our adoption of the Diataxis framework for structuring the Server Guide (for context, we are currently about halfway through this restructuring). Our Community team has put together a helpful set of resources to give contributors an overview of the changes we’re making.

The rest of this page is dedicated to giving you all the information you need to get started!

Make sure there are no pages on your chosen topic

As much as possible, we want the Server Guide to be easy to navigate, so we try to avoid repetition. New documentation should be created to fit into the hierarchy of pages which already exist. If you are unsure of where the page should go, or think we need a new section, please have a discussion about it first!

However, if you’ve spotted a gap and want to fill it…

Make a draft

You should have an idea in mind before you start about what style of page you want to write, according to the Diataxis framework:

  • A tutorial, to guide users through some aspect of Ubuntu Server in a sandboxed environment.
  • A how-to guide, providing the steps to achieve a particular task.
  • An explanation of a particular topic, or
  • A reference page.

You can write your draft online, directly in Discourse, if you want to see a preview of how the Markdown will render. If you prefer to work offline, software such as VSCode also has the ability to show a Markdown preview. See below for more information on writing and editing in Discourse.

If you get stuck on the draft stage and need some guidance or want a review before you post, you are very welcome to contact our technical author, Sally.

Post your content on the forum

As mentioned earlier, our documentation is created from selected forum posts, so the first step is to make a post in the “guide” section of the Server forum by clicking on the “+ New Topic” button on the top right of the linked page.

In your new post, enter the title (the level 1 heading) into the form field that says “Type title, or paste a link here”. This will be automatically rendered as the page title, so there’s no need to include a level 1 header in the body of the page, or to include any formatting around the header.

Paste the content of your page into the main field. Double check that the page is rendering as you expected using the preview window. Make sure you are happy with the page before you click on the “+ create topic” button. Depending on your Discourse trust level, you may not be able to edit your post after 24 hours has passed so make sure to address any unexpected differences right away.

Get your page added to the navigation

After your post is created, make a note of the generated URL. If you’re already in contact with our technical author, Sally, or another one of the admins on the Server section, you can send them the URL and they will add it to the correct part of the Server Guide for you.

After your page has been added to the site navigation, the next time you go back to the Server Guide documentation page, you should be able to see your page – congratulations!

Note:
If your page doesn’t appear within a few minutes, try refreshing the page to clear the cached version.

Guidance for writing

If you get stuck at all - please don’t hesitate to reach out for help. You can either leave a comment on this post for general queries, or contact Sally or one of our admins directly if you need more personal assistance.

General tips and style guide

Documentation consistency in terms of writing style is vital for a good user experience. In the Server Guide, we use the Canonical documentation style guide.

To make it more straightforward to publish your guide in our documentation, we recommend that you:

  • Use a spell checker (set to en-GB).

  • Be concise and to-the-point in your writing.

  • Check your links and test your code snippets to make sure they work as expected.

  • Link back to other posts on the topic, rather than repeating their content.

  • Expand your acronyms the first time they appear on the page, e.g. JavaScript Object Notation (JSON).

  • Try not to assume that your reader will have the same knowledge as you. If you’re covering a new topic (or something complicated) then try to briefly explain, or link to, things the average reader may not know.

  • If you have used some references you think would be generally helpful to your reader, feel free to include a “Further reading” section at the end of the page.

General tips for Discourse Markdown

Discourse uses the CommonMark flavour of Markdown, which is very similar to standard Markdown, so editing should be straightforward if you’re already familiar with Markdown. The main differences are highlighted here:

  • Linebreaks: Unlike standard Markdown, Discourse respects ALL linebreaks. Don’t add linebreaks at 79 characters unless it is really important for the output (e.g., in a code block).

  • Images: There are limitations involved in adding images, so we suggest avoiding them if possible. If the images are necessary then we can host them for you, just contact our technical author, Sally or one of the other admins for help.

  • Emoji: Please don’t use them. Although they look fine in Discourse forum posts, they don’t render well into the documentation.

Tips and best practices

  • If you’re not familiar with Markdown, don’t worry! you can always use the style toolbar at the top of the Discourse editing window instead.

  • If you would like to copy a Markdown element (like a table) and don’t know the code, you can always copy from an existing post. You can view the raw Markdown of a post by editing the URL in your browser – replace the /t/topic-name/ part with /raw/ instead.

    For example, our Discourse home page, https://discourse.ubuntu.com/t/ubuntu-server-documentation/11322 becomes https://discourse.ubuntu.com/raw/11322.

  • Try not to skip heading levels in your document structure, i.e., a level 2 header (##) should always be followed by a level 3 sub-header (###) not level 4.

  • For a numbered list, use 1. in front of each item. The numbering will be automatically rendered, so it makes it easier for you to insert new items in the list without having to re-number them all:

    1. This is the first item

1. This is the second

1. This is the third

  • Unless a list item includes punctuation, don’t end it with a full stop. If one item needs a full stop, add one to all the items.

  • Enclose a code block with three backticks ``` and include the language for syntax highlighting:

        ```yaml
    Some code block here
    ```

    Using text as the language is handy for displaying command output or plain text, since it does not highlight anything.

  • Use separate command input blocks from command output blocks. Avoid using a command line prompt (e.g. $ or #) in an input block if possible, and precede the output block with some kind of text that explains what’s happening. For example:

        ```bash
    uname -r
    ```

    Produces the following output:

    ```text
    4.14.151
    ```

  • Use a single backtick to mark inline commands and other string literals, like paths to files.

Feel free to reply to this post if you have any other questions - we will keep it updated with your suggestions and questions!

1 Like