User:SRodlund/Toolforge technical documentation improvements
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
- Toolforge User Surveys -- Annual Toolforge User Survey has consistently identified Toolforge | Cloud VPS technical documentation in need of improvement
- BSU Technical Documentation Audit
- Phab Epic: Megaticket covering many of the work requests for the Toolforge | Cloud VPS project
- Documenting Wikimedia Projects: Second half of Technical Talk covers the approach to improving the Toolforge | Cloud VPS collections
Proposal
- Review and reorganize existing Toolforge and Cloud VPS technical documentation for better readability. Update outdated information for existing pages with simple updates, and file tasks for ones which require more complicated updates
- Review, prioritize, and resolve current outstanding Phabricator tasks / requests for updates and improvements to Toolforge and Cloud VPS technical documentation
- Seek ways to improve organization and search-ability so users can find what they need
- Solicit additional feedback from Toolforge and Cloud VPS users regarding usefulness and accuracy of Toolforge and Cloud VPStechnical documentation (qualitative interviews and survey)
- Create and foster a feedback process, so users can surface issues with technical documentation and make requests for new technical documentation, which are addressed promptly and clearly
Measuring Success
Audiences for Toolforge & Cloud VPS documentation
Developer stories
- I am a new developer and/or new to the Wikimedia ecosystem, and I want to
- I am an experienced developer, and I want to
- I am a new developer and/or new to the Wikimedia ecosystem, and I want to understand what Toolforge is
- I am a new developer and/or new to the Wikimedia ecosystem, and I want to understand what is possible to do with Toolforge
- I am a new developer and/or new to the Wikimedia ecosystem, and I want to understand to how to use Toolforge to create a tool
- I am a new developer and/or new to the Wikimedia ecosystem, and I want to work with others to develop or maintain a tool
- I am an experienced or newer developer, and I want to learn about how other developers have used Toolforge
- I am an experienced developer, and I want to onboard experienced developers who are working on or with Toolforge
- I am an experienced developer, and I want to share information about how to perform a task or complete a process with a less experienced developer
- I am an experienced developer, and I want to find information about how Toolforge works
- I am an experienced developer, and I want to fix something that is broken about Toolforge
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
- Site organization and navigability -- Is the site well-organized. Can visitors find their way to the information they need or discover it easily?
- Coverage (Site/Topic level -- Toolforge as a main focus) -- What is the scope of the site/topic? Does it cover the relevant information? Are tangential but irrelevant topics included.
- Page level coverage -- does the page cover a specific topic or is there a hodgepodge of related information? Ideally, pages are focused on one area of coverage.
- Page level organization and navigability -- Do all pages follow a consistent structure? Is it easy to understand the flow of information?
- Readability -- Is the language readable. It should be simple and as low on the Flesh Kincaid scale as possible -- though this can be difficult with technical jargon (https://www.webfx.com/tools/read-able/check.php)
- Memorable -- Is the information memorable? Is it set up for the reader to learn / reference?
- Correct -- Is the information correct?
Monthly top page views
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.
Page level structure
- Are users able to find what they need using the current structure?
- Do pages follow basic templates that effectively convey information?
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
- What can you do? Ideas based on user stories.
- Merge&redirect this page somewhere: https://wikitech.wikimedia.org/wiki/Help:Toolforge/How_to (It doesn't seem to have a purpose)
- Create a standard template for what information will be on included on the Portal pages at https://wikitech.wikimedia.org/wiki/Main_Page
- Contact information should be included on all help pages, so folks can reach out for support and help.
Done Created Help:Cloud Services communication and transcluded it in 4 locations. Quiddity (talk)
- Look at the longer pages and give them a minimalist treatment so that they are easier to navigate and read.
- Look for duplicate information in different places on Wikitech; combine.
- Update: https://wikitech.wikimedia.org/wiki/Template:Toolforge_nav
- Look to the Wikipedia "Portal" guidelines for Portal pages on Wikitech (thinking about context and familiarity)
- https://en.wikipedia.org/wiki/Wikipedia:Portal/Guidelines
- https://en.wikipedia.org/wiki/Wikipedia:Portal
- Template:Portal How does / does the Portal template function on Wikitech?
- https://wikitech.wikimedia.org/wiki/User:Srodlund/Toolforge_technical_documentation_improvements/ideas_for_techincial_documentation_portal_design#Other
Spellings | usage
- See also: Help:Glossary
Spelling and usage is not always consistent across the documentation. Here are the current preferred spellings and usages:
- Tool Account (Group Account)
- maintainer (member of a tool account)
- Toolforge
- tool
- user
- Tools admin
- Tool Webpage
- Project admin
Definitions
- Tool Account (Group Account)
- maintainer (member of a tool account)
- Toolforge
- tool
- user
- Toolsadmin
- Tool Webpage
- User:Quiddity/doctemplates, list of (all?) documentation-related templates
- Toolhub#Visualizations related to Tools and Account creation
- Images: https://www.mediawiki.org/wiki/Help:Images
Big changes / page improvements
- https://wikitech.wikimedia.org/wiki/Portal:Toolforge
- https://wikitech.wikimedia.org/wiki/Portal:Toolforge/About_Toolforge
- https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Tool_Accounts
- https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Toolforge_quickstart
Tiny to-dos
Maybe file Phab tasks. Move to the subtle changes when finished.
- Make sure the links on the Toolforge Navbar on pages in Toolforge Portal link to the correct pages
- Change links in the sidebar to link to the appropriate pages. (https://wikitech.wikimedia.org/w/index.php?title=MediaWiki:Sidebar&action=edit)
Subtle Changes
- Remove the "See WMCS intro banner" from the top of pages to reduce confusion. WCMS intro is prominently featured from main and easy enough to find
- Make the Getting Started with WMCS page obsolete (It's too confusing for new people)
- Create a small "quickstart" page for Toolforge to link to from Portal
Pages I would like to delete
- https://wikitech.wikimedia.org/wiki/Help:Contents (just confusing and not useful)
- Help: Toolforge FAQ (Would like to combine this information with Help:Toolforge
- Help:Getting_Started -- Don't delete but rethink. This page has mixed coverage, and it can be REALLY confusing for a newcomer who isn't familiar with all the differences between our services and systems. There could be a lot more coverage for this in places that are separated by service/system.
Pages I would like to see
- How to get started with Toolforge - walkthrough w/decision tree
- How to set up an example tool & manage files (detailed w/screenshots)
- Structure -- What is the structure of Toolforge/how does it work/function holistically?
Nonpriority pages for update
- https://wikitech.wikimedia.org/wiki/Help:Glossary
- Wikitech sidebar should link to Portal rather than help pages for Toolforge and Cloud VPS
Pages outside Wikitech we should update
https://en.wikipedia.org/wiki/Wikipedia:Wikimedia_Cloud_Services