User:SRodlund/Toolforge technical documentation improvements
< User:SRodlund
Overview
There are a plethora of open tickets requesting new and improved Technical documentation for Toolforge. Improvements to documentation have also been consistently requested in the annual Toolforge survey. Gaps in consistency and documentation have been identified by users and collaborators. Many aspects of Toolforge are well-documented and some are not documented at all.
This can lead to an inconsistent experience for technical collaborators.
History and background
Proposal
Measuring Success
Audiences for Toolforge & Cloud VPS documentation
Developer stories
Cloud services audiences
https://www.mediawiki.org/wiki/Wikimedia_Cloud_Services_team/Our_audiences
Personas for technical documentation
https://www.mediawiki.org/wiki/User:APaskulin_(WMF)/Docs_Personas
Evaluation and improvement criteria
Monthly top page views
View top visited pages on Wikitech
Organization of technical documentation
Wikitech Overall
March 2019 - technical documentation in the Wikitech namespace is not formally organized beyond the usage of categories at this time. Visitors to the site might be confused by its current structure, which visually mimics a more hierarchical website (see main page). Users who do not know the differences between cloud services and tech ops may be confused. Introductory, getting started, and informational portals for different products and services appear on the same main-page. When the visitor clicks through the links on the main page they will encounter pages of vastly different purposes, conveying information in vastly different ways. These pages are basically siloed. Once a user leaves the main page, they are just where they are with little guidance to help them find what they need.
Very rough outline of technical documentation on Wikitech (March 2019)

Page level structure
Language and readability
Make sure the documentation is written for easy readability. It will be hard to gauge on flesh kincaid w/all the jargon and technical language but keep simplifying and scaling back.
Tickets on Phabricator for individual pages
Update and improve Toolforge technical documentation
Key Toolforge pages
See Epic: https://phabricator.wikimedia.org/T203131
Recommendations
Spellings | usage
See also: Help:Glossary
Spelling and usage is not always consistent across the documentation. Here are the current preferred spellings and usages:
Definitions
Documentation templates and related visualizations
Big changes / page improvements
Tiny to-dos
Maybe file Phab tasks. Move to the subtle changes when finished.
Subtle Changes
Pages I would like to delete
Pages I would like to see
Nonpriority pages for update
Pages outside Wikitech we should update
https://en.wikipedia.org/wiki/Wikipedia:Wikimedia_Cloud_Services
Last edited on 28 October 2019, at 19:43
Wikitech
Content is available under CC BY-SA 3.0 unless otherwise noted.
Privacy policy
Terms of Use
Desktop
HomeRandomLog inSettingsDonateAbout WikitechDisclaimers
WatchEdit