Page MenuHomePhabricator

Improve mw:Documentation as a landing page for technical documentation writers
Closed, ResolvedPublic


(The original task description doesn't fully capture the work being done to overhaul this page and its related content in 2022-2023, please see task updates below in thread)

If I remember correctly I mentioned this page at the Docs offsite.

Event Timeline

Aklapper triaged this task as Medium priority.Mar 11 2021, 6:05 AM
Aklapper created this task.
Aklapper updated the task description. (Show Details)

@Yasharth291: Hi, we usually don't assign tasks and the questions above first need discussion.

Probably going to take a look at this at some point between September 2021 - March 2022

CC'ing @TBurmeister as I'd love more input and as I don't want to collide with potential plans

A large overhaul and update the the content at mw:Documentation is likely to be part of our FY22/23 work. Planning is happening in the next few weeks; will update this task as we decide upon more specific goals and create tasks for each quarter's work.

Small update: In Q2 of FY 22/23 I started working on translating the most generally-applicable results of our research about assessing document collections into a process at

Today I completed a new landing page structure for the collection ; this is still in draft form as I build out content in the subpages and get feedback. I discovered the Noun Project icons on Commons and am having some Friday fun with the icons on the page for now, while it's a draft :-)

The new / drafted content structure:

Documentation (landing page) has 4 major subpages:

  1. Where are the docs? --> Documentation/Find docs
  2. Improve your docs --> Documentation/Toolkit
  3. Learn about writing --> Documentation/Technical_style_guides_and_templates
  4. Get involved in doc work --> Documentation/Contribute

The landing page consists only of a brief overview, the aforementioned section links, and a new section for how to get support and doc help.

Existing (and some newly-created) content fits into these 4 sections as follows:

Find docs:

  • Documentation/Find_docs: content moved from old landing page; can be built out with additional content as needed. Added links and reference to Developer Portal.

Improve your docs (many older template & process pages need to be organized / reviewed / cleaned up):

  • Documentation/Toolkit (landing page)
  • Documentation/Toolkit/Collection audit
  • Documentation/Toolkit/Collection audit/Assess
  • Documentation/Toolkit/Collection audit/Prioritize
  • Documentation/Toolkit/Collection audit/Survey
  • Documentation/Toolkit/Content audit
  • Documentation/Toolkit/How-to guide review
  • Documentation/Toolkit/Landing page review
  • Documentation/Toolkit/Quick review
  • Documentation/Toolkit/Style review
  • Documentation/Toolkit/Tutorial review
  • Documentation/Walkthoughs, how-tos and tutorials templates
  • Documentation/Audiences for Wikimedia technical documentation
  • Documentation/Documentation Review Processes
  • Documentation/API Documentation Template
  • Documentation/Library Documentation Template
  • Documentation/Patterns
  • Documentation/Patterns/How-to guide
  • Documentation/Patterns/Landing page
  • Documentation/Patterns/Tutorial
  • Documentation/Quick Start Guides Documentation Template
  • Documentation/Review template
  • Documentation/Review template/Technical decision forum
  • Documentation/Services

Learn about writing:

  • Documentation/Technical_style_guides_and_templates (landing page)
  • Documentation/Style guide
  • Documentation/Technical documentation templates and suggestions

Get involved in doc work:

  • Documentation/Contribute (landing page)
  • Contribute to docs:
    • Documentation/Contribute/New technical writers
    • Participate in doc testing and provide doc feedback
      • Documentation/Hackathon 2022 docs discussions
  • Documentation/Technical documentation prioritization: moved and renamed "Documentation/Contribute/Filing documentation tasks"
  • Outreach programs focused on tech writing:
    • Season_of_Docs/Past_projects (marked as obsolete, need to do something better with this)
  • Learn about doc strategy:
    • Documentation/Technical_communication_goals
    • Documentation/Maturity model for MediaWiki technical documentation

Pages marked for Deletion so far:

  • Documentation/Improvement
  • Documentation/Improvement/status
  • Documentation/Technical documentation community and outreach programs (content moved to Documentation:Contribute)
  • Documentation/Planning for better technical documentation (content sharded into the sections of Documentation/Toolkit/Collection audit)
  • Documentation/Resources for technical writers (content moved into Documentation/Technical_style_guides_and_templates)
  • Documentation/Technical writer guide: content moved into Documentation/Technical_style_guides_and_templates and Documentation/Contribute
  • Documentation/Technical documentation prioritization: moved and renamed "Documentation/Contribute/Filing documentation tasks"
TBurmeister changed the task status from Open to In Progress.Oct 21 2022, 5:48 PM

The major changes are:

  • Changed the site architecture to focus even more on the most common doc-related user journeys and use a more mobile-friendly layout
  • Removed a ton of outdated links and "nice to know" but ultimately overwhelming content about writing
  • Revised doc prioritization / bug filing content
  • Revised and more honest "how to get involved in doc work" page
  • Combined and simplified the list and description of where tech docs live; added prominent links to Dev Portal
  • Launched new Doc Toolkit as an entry point for review checklists, collection audit processes, and doc templates
  • Added clearer communication paths for getting support / asking questions