Technical documentation checklist and templates

• Wikitech Main page
• Cloud VPS technical documentation
• Toolforge technical documentation
• Help and communication

Overview

This page contains a checklist for individuals who are writing technical documentation on Wikitech -- primarily Cloud VPS and Toolforge.

Before you begin

• Become familiar with the MediaWiki Technical Documentation Style Guide.
• Decide what kind of technical document is most appropriate.
• Gather your information. Make sure you have all of your links, data, that you will need to include.

Useful resources

• Wikitech documentation templates is a very useful list of templates that can enhance your technical documentation on Wikitech.
• MediaWiki Technical Documentation Style Guide
• Technical documentation templates and suggestions on MediaWiki. You may find something useful here you would like to import to your documentation on Wikitech.

Technical documentation checklist

At minimum, each documentation page for Cloud VPS and Toolforge should include:

1. Descriptive Title: The title should be descriptive and specific. This helps visitors decide whether they would want to use the page. For example: Accessing Instances on Cloud VPS is much better than Instances.
2. Project or page-specific templates:
   1. Cloud VPS Navbox: {{Cloud VPS nav}}
   2. Toolforge Navbox: {{Template:Toolforge nav}}
   3. Contact Us / Communication: {{:Help:Cloud Services communication}}
3. An Overview: This is a short statement about the document, who it is for, why it is useful.
4. Prerequisites or Before you Begin: This is a checklist of what a person will need in order to follow the documentation. This may include the type of account people will need, software, rights, knowledge level, etc. You may want to link to information (for example, how to obtain user roles, rights, etc).
5. Descriptive section headers: Section headers should be descriptive and specific. This helps visitors decide if they need to read the entire page or just a section. Think about the most important information that the section will convey. Make sure that this is the header.
6. See Also:
7. Categories: For Toolforge or Cloud VPS, Categories: Category:Cloud VPS, Category:Toolforge, Category:Administration or Category:Administrator (for Admin pages), Category:Documentation, Category:Cloud Services

Documentation templates

Page templates

• Cloud VPS: You can copy/paste the source code from the Cloud VPS technical documentation template into new documentation pages to help get you started.
• Toolforge: You can copy/paste the source code from the Toolforge technical documentation template into new documentation pages to help get you started.

Formatting and content templates

Wikitech has various technical document markup templates to format your text, add callouts, and markup your content.

Technical documentation review

It can be helpful for new and updated technical documentation to go through a technical review.

1. Create a Phabricator task with the following: Technical Review for: link to page
2. Tags: Cloud VPS or Toolforge and Documentation
3. Subscribers: Yourself and others who may be able to review
4. Description: "link to page" has been recently created or updated. It requires a technical review for accuracy. Is there any outdated, wrong, or missing information?"
5. You may want to link the ticket from the page you that needs review. Make sure to subscribe and follow-up to changes in a timely manner.

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support

• Chat in real time in the IRC channel #wikimedia-cloud ^connect, the bridged Telegram group, or the bridged Mattermost channel
• Discuss via email after you have subscribed to the cloud@ mailing list

Stay aware of critical changes and plans

• Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
• Read the News wiki page

Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)