User:Triciaburmeister/Toolforge docs
Done This project is complete.
This is a summary of Toolforge-specific changes I'm proposing as part of a larger technical documentation project to improve the overall usability and navigation of the Cloud Services docs. Because there are a lot of moving pieces to this, I'm trying to present them here as succinctly as possible, with links to my draft revisions.
Summary of proposed changes
Right now, WMCS has both Portal: and Help: landing pages for Toolforge. The Portal: pages have as subpages all the Admin docs. The Help: page mostly duplicates navigation that is (or can be) in the nav template. I propose to:
- Remove the user-focused Toolforge nav template from Portal:Toolforge, so that Portal: page serves all user audiences, acting only as a navigational landing page for accessing either the admin docs or the user docs. (This is its current function, but it can be revised to perform that function more effectively).
- Revise Help:Toolforge to serve as a more comprehensive entry point for Toolforge users. This landing page should serve the following functions:
- Provide a high-level overview of the product's main features, capabilities, and limitations
- Alert prospective users to any prerequisites to using the product
- Provide links to "getting started" content, which includes: a more in-depth overview of the product and its core concepts (About_Toolforge), a quick start guide, tutorials or ways to get hands-on practices before getting started).
- Revise About_Toolforge to function as a more robust conceptual overview doc, to enable readers to build a mental model of how Toolforge works.
- Revise the Toolforge quickstart and How-To docs.
- Create a new nav template for the Toolforge admin docs.
- Move any user-focused subpages of Portal:Toolforge to be subpages of Help:Toolforge.
Revised information architecture and landing pages
| Level 1 | Level 2 | Level 3 |
|---|---|---|
| Entry point | Cross-collection landing pages | Product landing page(s) |
| Wikitech:Main_page | Portal:Toolforge | Help:Toolforge |
| Portal:Toolforge/Admin | ||
| Cloud Services introduction | [various] |
Revised (or to be revised) content pages
From the revised Help:Toolforge page, a user has access to all the docs (via the revised navigation template and links in the page text). Users who follow the more guided path supported by the landing page structure are offered the following as primary next steps after they are done with the landing page:
- Learn more - Conceptual overview of Toolforge: User:Triciaburmeister/Sandbox/About_Toolforge
- Quick start - How-to doc for basic setup steps and how to ssh (revisions still TODO: Help:Toolforge/Quickstart). Should cover, at minimum, how to create a Toolforge tool and SSH into Toolforge.
- Learn with tutorials - Navigational doc for tutorials and notebooks focused on beginners (revisions still TODO: Help:Toolforge/Quickstart#Host your first tool on a tool account; other docs linking to useful PAWS notebooks for learning how to use the APIs).
- Currently working on implementing subcategories to provide navigation to tutorials and how-to docs by language using page metadata instead of a manually-maintained page:
https://wikitech.wikimedia.org/wiki/Category:Tutorials
Feedback is welcome!
You can leave feedback on the Phabricator task, on the Talk page for this page, or any of the sandbox pages linked above. Thanks!