You are browsing a read-only backup copy of Wikitech. The primary site can be found at wikitech.wikimedia.org

User:SRodlund/Toolforge technical documentation improvements

From Wikitech
Jump to navigation Jump to search

Overview

This page contains thoughts and ideas for creating structured and substantive improvements to Toolforge technical 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

Evaluation and improvement

  • 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?

Audiences

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

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.

File:Wikitech Site Map Feb 2019.svg

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

Portal:Toolforge

  • Portal:Toolforge AKA Portal: Tool Labs (Redirected)
  • phab: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?
    • Yes Done 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/FAQ

Portal:Toolforge/Admin

Portal:Toolforge/Nodes

Help:At a glance: Cloud VPS and Toolforge

Potential Structure and Content Notes

ToolForge Portal:

Toolforge USER help

  • Work on this first (sections)

-- For this namespace (Own Navbar of selected stuff) -- Curated category for these pages (TOOLFORGE USER DOCUMENTATION)


Toolforge ADMIN help (under portal but needs to be moved to help)

  • Work on second (sections)

-- For this namespace (A navbar of selected information) -- Curated category for these pages (TOOLFORGE ADMIN DOCUMENTATION)

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

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:

  • Tool Account (Group Account)
  • maintainer (member of a tool account)
  • Toolforge
  • tool
  • user
  • Toolsadmin
  • Tool Webpage

Definitions

  • Tool Account (Group Account)
  • maintainer (member of a tool account)
  • Toolforge
  • tool
  • user
  • Toolsadmin
  • Tool Webpage

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

  • 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

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