While Toolforge docs for both admins and end users exist on Wikitech, there is currently no high-level overview of the system architecture as a whole.
The primary audiences of this documentation would be:
@aborrero has already created a stub for this here: https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Admin/System_Overview
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Resolved | TBurmeister | T321582 WMCS doc improvements for FY22/23: Improve the navigability, freshness, and topic coverage of Cloud Services docs | |||
| Open | None | T342046 Update Toolforge and Cloud VPS Admin Documentation | |||
| Open | None | T327760 Create a high-level overview of Toolforge system architecture |
There is a bit of related content at https://wikitech.wikimedia.org/wiki/Portal:Toolforge/About_Toolforge. It should probably be combined with the info at https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Admin/System_Overview or connected, but in a way that provides affordances for both users who only want the high-level info and users that need to navigate further into the detailed system info.
The About Toolforge page to me looks like something intended for end users, not potential contributors or admins.
Agree, although similar to @TBurmeister, I do think it should be possible to adapt About Toolforge to be an entrypoint for any newcomer, then link to the more detailed technical overview proposed here from e.g. the "How is Toolforge structured?" section.
The paths for new tool maintainers and new Toolforge admins are very different and I'm not sure if it's possible to fit both of them into the same page.
Anyways, I've also noticed that the About Toolforge largely duplicates Help:Toolforge and I'd prefer to merge those two if possible.
About Toolforge feels like a conceptual introduction, while Help:Toolforge is more like an index or glossary of Toolforge topics. I support these two pages being merged, though it's possible it would make more sense to get rid of Help:Toolforge and instead provide a better navigation template for the Toolforge portal and also improve the page structure at https://wikitech.wikimedia.org/wiki/Portal:Toolforge. I was surprised to discover that About_Toolforge isn't linked in the nav template. There are multiple pages that have "quick start" and "what is toolforge" content on them, which should be consolidated.
@taavi, I'm going to be working on improving the navigation structure and organization of the Cloud docs this quarter (T327319), but the specific details of what I'll prioritize aren't finalized yet. Would you like to collaborate on designing an improved information structure for the Toolforge portal? Are you interested in helping with how the docs are organized overall, and/or would you like to work on improving and merging the content of individual pages as you mentioned above?
As part of T341364 I will make updates to About_Toolforge and integrate the content from Help:Toolforge into a revised Toolforge landing page and/or navigation template. I created a separate task for that since it's part of a larger project to improve Toolforge user docs, while this task is focused on the Toolforge admin docs (the two tasks have different focus areas, and I am working on the user-focused content, not this admin stuff :-)).