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 ===
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).
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 	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 , 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.