You are browsing a read-only backup copy of Wikitech. The live site can be found at wikitech.wikimedia.org
Difference between revisions of "Technical documentation checklist and templates"
Jump to navigation
Jump to search
imported>SRodlund m (SRodlund moved page User:SRodlund/Technical documentation checklist and templates to Technical documentation checklist and templates: Moving to mainspace) |
imported>SRodlund |
||
| (4 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Sidebar | {{Sidebar | ||
| style = background: white; padding:10px; padding-{{dir|{{pagelang}}|left|right}}:13px; margin:{{dir|{{pagelang}}|5px 12px 5px 0|5px 0 5px 12px}}; width: 350px; | | style = background: white; padding:10px; padding-{{dir|{{pagelang}}|left|right}}:13px; margin:{{dir|{{pagelang}}|5px 12px 5px 0|5px 0 5px 12px}}; width: 350px; | ||
| name = | | name = :Technical documentation checklist and templates | ||
| headingstyle = font-size: 130%; padding: .5em; | | headingstyle = font-size: 130%; padding: .5em; | ||
| contentstyle = text-align: {{dir|{{pagelang}}|right|left}}; font-size: 14px; padding: .5em; line-height: 1.5; | | contentstyle = text-align: {{dir|{{pagelang}}|right|left}}; font-size: 14px; padding: .5em; line-height: 1.5; | ||
| Line 25: | Line 25: | ||
== Useful resources == | == Useful resources == | ||
* [[Wikitech_documentation_templates | Wikimedia documention templates]] is a very useful list of templates that can enhance your technical documentaton on Wikitech. | |||
* [[mw:Documentation/Style_guide|MediaWiki Technical Documentation Style Guide]] | * [[mw:Documentation/Style_guide|MediaWiki Technical Documentation Style Guide]] | ||
* [ | * [[mw:Documentation/Technical_documentation_templates_and_suggestions | 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 == | == Technical documentation checklist == | ||
| Line 34: | Line 35: | ||
# '''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''. | # '''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''. | ||
# '''Project or page-specific templates''': | # '''Project or page-specific templates''': | ||
## Cloud VPS Navbox: <nowiki> {{Cloud VPS nav}} </nowiki> | ## Cloud VPS Navbox: <code><nowiki>{{Cloud VPS nav}}</nowiki></code> | ||
## Toolforge Navbox: <nowiki> {{Template:Toolforge nav}} </nowiki> | ## Toolforge Navbox: <code><nowiki>{{Template:Toolforge nav}}</nowiki></code> | ||
## Contact Us / Communication: <nowiki> {{:Help:Cloud Services communication}} </nowiki> | ## Contact Us / Communication: <code><nowiki>{{:Help:Cloud Services communication}}</nowiki></code> | ||
# '''An Overview''': This is a short statement about the document, who it is for, why it is useful | # '''An Overview''': This is a short statement about the document, who it is for, why it is useful. | ||
# '''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). | # '''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). | ||
# '''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. | # '''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. | ||
| Line 52: | Line 53: | ||
=== Helpful technical document markup templates === | === Helpful technical document markup templates === | ||
A set of [https://www.mediawiki.org/wiki/Documentation/Style_guide/templates technical document markup templates] are available on MediaWiki.org. Some or all may need to be localized for Wikitech. | A set of [https://www.mediawiki.org/wiki/Documentation/Style_guide/templates technical document markup templates] are available on MediaWiki.org. Some or all may need to be localized for Wikitech. | ||
== Technical documentation review == | |||
It can be helpful for new and updated technical documentation to go through a technical review. | |||
# Create a Phabricator task with the following: Technical Review for: ''link to page'' | |||
# Tags: Cloud VPS or Toolforge and Documentation | |||
# Subscribers: Yourself and others who may be able to review | |||
# 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?" | |||
# 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. | |||
{{:Help:Cloud Services communication}} | {{:Help:Cloud Services communication}} | ||
Latest revision as of 16:58, 7 September 2021
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
- Wikimedia documention templates is a very useful list of templates that can enhance your technical documentaton 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:
- 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.
- Project or page-specific templates:
- Cloud VPS Navbox:
{{Cloud VPS nav}} - Toolforge Navbox:
{{Template:Toolforge nav}} - Contact Us / Communication:
{{:Help:Cloud Services communication}}
- Cloud VPS Navbox:
- An Overview: This is a short statement about the document, who it is for, why it is useful.
- 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).
- 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.
- See Also:
- Categories: For Toolforge or Cloud VPS, Categories: Cloud VPS, Toolforge, Administration or Administrator (for Admin pages), Documentation, 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.
Helpful technical document markup templates
A set of technical document markup templates are available on MediaWiki.org. Some or all may need to be localized for Wikitech.
Technical documentation review
It can be helpful for new and updated technical documentation to go through a technical review.
- Create a Phabricator task with the following: Technical Review for: link to page
- Tags: Cloud VPS or Toolforge and Documentation
- Subscribers: Yourself and others who may be able to review
- 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?"
- 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
We communicate and provide support through several primary channels. Please reach out with questions and to join the conversation.
| Way | Connect | Best for |
|---|---|---|
| Phabricator Workboard | #Cloud-Services | Task tracking and bug reporting |
| IRC Channel | #wikimedia-cloud connect Telegram bridge mattermost bridge |
General discussion and support |
| Mailing List | cloud@ | Information about ongoing initiatives, general discussion and support |
| Announcement emails | cloud-announce@ | Information about critical changes (all messages mirrored to cloud@) |
| News wiki page | News | Information about major near-term plans |
| Cloud Services Blog | Clouds & Unicorns | Learning more details about some of our work |
| Wikimedia Technical Blog | techblog.wikimedia.org | News and stories from the Wikimedia technical movement |