Wikimedia Cloud Services team/Documentation guide

From Wikitech
Jump to navigation Jump to search

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

Information architecture of Toolforge docs
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

Information architecture of Cloud VPS docs
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).
There isn't actually a "portal" namespace on Wikitech; these pages are just created with "portal" in their title.

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

https://dumps.wikimedia.org/

T348037
Dumps admin docs and

mw:SQL/XML_Dumps

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 n/a
Wiki replicas admin docs
Doc authors should be aware of a known issue (phab:T244256#5849649 and phab:T242931) with how Wikitech navigation templates display on mobile.

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:

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.