Wikimedia Cloud Services team/Documentation guide
This page provides an overview of how technical documentation for WMCS products and services is structured, and things maintainers should know to help with the work of improving the docs.
Structure of WMCS doc collections on Wikitech
WMCS owns many services. This page documents only the collection structure for the services that have undergone a content audit as of October 2023.
Toolforge documentation
| Level 1 | Level 2 | Level 3 | Level 4+ |
|---|---|---|---|
| Entry point | Cross-collection landing pages | Product landing page(s) | Content pages |
| Main Page | Portal:Toolforge | Help:Toolforge (user docs landing page) | pages in Category:Toolforge |
| Portal:Toolforge/Admin (admin docs landing page) | subpages of Toolforge/Admin(Category:Toolforge_admin has not been consistently applied) | ||
| Cloud Services introduction | [various] |
Cloud VPS documentation
| Level 1 | Level 2 | Level 3 | Level 4+ |
|---|---|---|---|
| Entry point | Cross-collection landing pages | Product landing page(s) | Content pages |
| Main Page | Portal:Cloud_VPS | Help:Cloud_VPS (user docs landing page) | pages in Category:Cloud_VPS |
| Portal:Cloud_VPS/Admin (admin docs landing page) | subpages of Cloud_VPS/Admin(Category:VPS_admin has not been consistently applied) | ||
| Cloud Services introduction | [various] |
Portal pages
These pages are in Category:Portals. Their primary purpose is navigation. They guide users to more specific landing pages.
- Portal:Toolforge provides navigation to either the Toolforge user docs, or the Toolforge admin docs.
- Portal:Cloud_VPS provides navigation to either the Cloud VPS user docs, or the Cloud VPS admin docs.
- Portal:Data_Services provides navigation to some landing pages and some content pages. It should be considered for revision (phab:T348024).
phab:T327319 refined the structure and content of the Toolforge and Cloud VPS pages to be more consistent and align with the document types framework, so that portal pages only serve as navigation tools, and any significant textual or introductory content resides on landing pages.
Landing pages and collection navigation
These pages should be in Category:Landing_page, but so far only the Toolforge and Cloud VPS landing pages have been revised to align with the documentation patterns for their doc type. Because landing pages are the primary entry point for navigation a collection of documents, they should each have a navigation menu. Landing pages should cover a basic set of information that helps readers decide if they should keep reading about or start using the product/service (see mw:Documentation/Landing_pages).
| Product/service landing page | Navigation menu |
|---|---|
| Cloud VPS user docs | Template:Cloud VPS nav |
| Cloud VPS admin docs | |
| Dumps user docs and | T348037 |
| Dumps admin docs and | T348037 |
| PAWS user docs | n/a, embedded in landing page |
| PAWS admin docs | n/a |
| Quarry user docs | n/a |
| Quarry admin docs | n/a |
| Superset user docs | n/a |
| Toolforge user docs | Template:Toolforge nav |
| Toolforge admin docs | Template:Toolforge nav adminT345109 |
| Wiki replicas user docs | Template:Data Services nav |
| Wiki replicas admin docs |
Content pages
Content pages are docs that provide information more than navigation. Wikitech has categories for these major types of documents, but the metadata has not been systematically applied (it was only created as part of phab:T327319, and only applied to pages revised as part of that project. See phab:T348047 and phab:T348049).
Overviews
- Help:Cloud_Services_introduction is a high-level, cross-collection overview that seeks to provide enough information to help readers navigate to the best product/service for their use case. It doesn't provide in-depth product information, since that belongs on the product landing and content pages.
- Portal:Toolforge/About_Toolforge is the product overview for Toolforge.
- Portal:Cloud_VPS/Infrastructure is a very infrastructure-focused overview of how Cloud VPS works. There may be a need for a more broad, end-user focused overview, but that should be determined in consultation with the WMCS team and after more user research.
How-to guides
Toolforge has two how-to guides that are important for beginners:
- Help:Toolforge/Quickstart - covers the basic steps to get up and running as a Toolforge user
- Help:Toolforge/Tool_Accounts - covers the basic steps the user will need to know as soon as they have access to Toolforge and want to actually start doing things.
Cloud VPS doesn't have a "quickstart" like Toolforge; but Help:Cloud_VPS_project serves a similar purpose to the Help:Toolforge/Tool_Accounts doc for Toolforge: it covers the first things you'll need to know how to do once you have finished onboarding.
Tutorials
Toolforge tutorials need some love. phab:T203131 gathers together multiple open tasks about tutorials (along with other doc tasks). There is a series of "my first X tool" tutorials, but (without deep review) they seem to be missing some key info and some of them may not actually be "tutorials", they might just be how-to guides. Tutorials should result in the user actually creating a thing or running the sample tool as the outcome of the tutorial.
As part of the Cloud Docs Refresh in 2023, tech writers talked about how PAWS notebooks can serve as a useful learning and prototyping tool to help people learn how to use Wikimedia APIs and test code before implementing it as a tool. Future doc work could investigate whether PAWS or other Jupyter notebooks would be a useful and sustainable way to provide tutorials related to Toolforge.
There are almost no tutorials for Cloud VPS, probably because it's for advanced users, each of whom will be doing something very specific? This would also be worth investigating further through conversation with the WMCS team and user research.
Documentation task tracking
- phab:T203131 gathers together multiple tasks for Cloud VPS and Toolforge docs.
- Doc tasks should be tagged with the Documentation tag, and one of the Cloud Services project tags listed at phab:project/profile/832/.
- When you create a task for doc-related work, you should add a note in the wiki page so that readers are aware of any issues with the content, and can help fix it if they're able. Here is an example.