User:JAufrecht (WMF)/T222243

,d 88                           MM88MMM ,adPPYba,  8b,dPPYba, 88  a8"     "8a 88P'    "8a    88   8b       d8 88       d8    88,  "8a,   ,a8" 88b,   ,a8" "Y888 `"YbbdP"' 88`YbbdP"' 88                             88

Overview
This page contains thoughts and ideas for creating structured and substantive improvements to Toolforge technical documentation

Audiences
https://www.mediawiki.org/wiki/Wikimedia_Cloud_Services_team/Our_audiences

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.



Page level structure


 * Are users able to find what they need using the current structure?
 * Do pages follow basic templates that effectively convey information?

Tickets on Phabricator for individual pages
Update and improve Toolforge technical documentation

Portal:Toolforge

 * Portal:Toolforge AKA Portal: Tool Labs (Redirected)
 * T204132
 * Consistently, the most viewed "toolforge" related page
 * Entry point for many seeking information and help about Toolforge
 * This page is linked to frequently from outside sources; its content and organization is key.
 * Getting Started
 * Links to Help/How-to Documentation
 * Links to About Documentation
 * Links to Reference Documentation

Questions
 * Why is this called a Portal?
 * What are the key reasons visitors come to this page?
 * Information about Toolforge?
 * For Help and support content?
 * By mistake?
 * Does the layout/visual design of this page aid users in finding the information they need?
 * Image in Toolforge specific navbar is for Cloud Services. Is this confusing?
 * ✅ Its actually the old "tool labs" logo. Lets update it to be the correct one! BryanDavis (talk)

Help:Toolforge
This is consistently viewed in the top 3 pages on Wikitech PRIORTY
 * Help:Toolforge
 * Make sure this is linked to Toolforge:Portal

Help:Toolforge/FAQ

 * Help: Toolforge FAQ
 * Make sure this is linked to Toolforge:Poral

Portal:Toolforge/Admin

 * Portal: Toolforge/Admin

Portal:Toolforge/Nodes

 * Portal:Toolforge/Nodes

Help:At a glance: Cloud VPS and Toolforge

 * Help:At a glance: Cloud VPS and Toolforge
 * Make sure this is linked under Cloud VPS ad Toolforge Portals

Potential Structure and Content Notes
ToolForge Portal:

Toolforge USER help -- For this namespace (Own Navbar of selected stuff) -- Curated category for these pages (TOOLFORGE USER DOCUMENTATION)
 * Work on this first (sections)

Toolforge ADMIN help (under portal but needs to be moved to help) -- For this namespace (A navbar of selected information) -- Curated category for these pages (TOOLFORGE ADMIN DOCUMENTATION)
 * Work on second (sections)

"My First XYZ Tool" should be highlighted under the "How To" section

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

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.
 * ✅ 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.
 * 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
 * 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

Language
Keeping things consistent


 * Tool Account (Both words always capitalized)
 * Toolforge (capitalized as a proper noun)
 * tool (lower case)

Documentation templates and related visualizations

 * User:Quiddity/doctemplates, list of (all?) documentation-related templates
 * Toolhub
 * Images: https://www.mediawiki.org/wiki/Help:Images

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

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

88         88          88 88                                ""          88          88 88                                            88          88 88             88,dPYba,,adPYba,  88  ,adPPYb,88  ,adPPYb,88 88  ,adPPYba, 88P'  "88"    "8a 88 a8"    `Y88 a8"    `Y88 88 a8P_____88  88      88      88 88 8b       88 8b       88 88 8PP""""""" 88     88      88 88 "8a,   ,d88 "8a,   ,d88 88 "8b,   ,aa  88      88      88 88  `"8bbdP"Y8  `"8bbdP"Y8 88  `"Ybbd8"'

Overview
This page contains thoughts and ideas for creating structured and substantive improvements to Toolforge technical documentation

Audiences
https://www.mediawiki.org/wiki/Wikimedia_Cloud_Services_team/Our_audiences

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.



Page level structure


 * Are users able to find what they need using the current structure?
 * Do pages follow basic templates that effectively convey information?

Tickets on Phabricator for individual pages
Update and improve Toolforge technical documentation

Portal:Toolforge

 * Portal:Toolforge AKA Portal: Tool Labs (Redirected)
 * T204132
 * Consistently, the most viewed "toolforge" related page
 * Entry point for many seeking information and help about Toolforge
 * This page is linked to frequently from outside sources; its content and organization is key.
 * Getting Started
 * Links to Help/How-to Documentation
 * Links to About Documentation
 * Links to Reference Documentation

Questions
 * Why is this called a Portal?
 * What are the key reasons visitors come to this page?
 * Information about Toolforge?
 * For Help and support content?
 * By mistake?
 * Does the layout/visual design of this page aid users in finding the information they need?
 * Image in Toolforge specific navbar is for Cloud Services. Is this confusing?
 * ✅ Its actually the old "tool labs" logo. Lets update it to be the correct one! BryanDavis (talk)

Help:Toolforge
This is consistently viewed in the top 3 pages on Wikitech PRIORTY
 * Help:Toolforge
 * Make sure this is linked to Toolforge:Portal

Help:Toolforge/FAQ

 * Help: Toolforge FAQ
 * Make sure this is linked to Toolforge:Poral

Portal:Toolforge/Admin

 * Portal: Toolforge/Admin

Portal:Toolforge/Nodes

 * Portal:Toolforge/Nodes

Help:At a glance: Cloud VPS and Toolforge

 * Help:At a glance: Cloud VPS and Toolforge
 * Make sure this is linked under Cloud VPS ad Toolforge Portals

Potential Structure and Content Notes
ToolForge Portal:

Toolforge USER help -- For this namespace (Own Navbar of selected stuff) -- Curated category for these pages (TOOLFORGE USER DOCUMENTATION)
 * Work on this first (sections)

Toolforge ADMIN help (under portal but needs to be moved to help) -- For this namespace (A navbar of selected information) -- Curated category for these pages (TOOLFORGE ADMIN DOCUMENTATION)
 * Work on second (sections)

"My First XYZ Tool" should be highlighted under the "How To" section

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

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.
 * ✅ 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.
 * 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
 * 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

Language
Keeping things consistent


 * Tool Account (Both words always capitalized)
 * Toolforge (capitalized as a proper noun)
 * tool (lower case)

Documentation templates and related visualizations

 * User:Quiddity/doctemplates, list of (all?) documentation-related templates
 * Toolhub
 * Images: https://www.mediawiki.org/wiki/Help:Images

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

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

88                                                                   88                       ,d      ,d 88                      88      88                                   88,dPPYba,   ,adPPYba, MM88MMM MM88MMM ,adPPYba,  88,dPYba,,adPYba, 88P'   "8a a8"     "8a  88      88   a8"     "8a 88P'   "88"    "8a 88      d8 8b       d8  88      88   8b       d8 88      88      88 88b,  ,a8" "8a,   ,a8"  88,     88,  "8a,   ,a8" 88      88      88  8Y"Ybbd8"'   `"YbbdP"'   "Y888   "Y888 `"YbbdP"'  88      88      88