Page MenuHomePhabricator

Expand good practices / offer boilerplates how to create new technical documentation wiki pages
Closed, DeclinedPublic

Description

Dumping thoughts relate to expanding https://www.mediawiki.org/wiki/Documentation and subpages, such as https://www.mediawiki.org/wiki/Documentation/Style_guide#Structuring_pages . See also T277128: Improve mw:Documentation as a landing page for technical documentation writers.

About page creation itself:

  • Before creating a page, first search for existing pages to potentially expand - cf https://meta.wikimedia.org/wiki/Learning_patterns/Every_new_page_starts_off_unwatched
  • Before creating a page, first search for existing top-level pages (e.g. mw:Phabricator) to avoid creating new top-level pages (e.g. mw:Phabricator_aspect); encourage creation of subpages instead (mw:Phabricator/Aspect))
  • After creating a page, check Special:WhatLinksHere in the sidebar and make sure that the page is linked from relevant pages, e.g. a top page, or (and that is harder to find and identify) any related "link hub style" templates (random example, as I lack better words: meta:Template:Communications

About technology and people:

  • I may feel intimidated by module / template / <translate> stuff on pages (cf. T131516: Reduce or eliminate the need for the user to touch <translate> tags and unit markers) that I want to edit. Creating a new page with partial duplication, instead of potentially breaking something that I don't fully understand, can be easier and more comfortable.
  • People take paths of least residence: I'd rather copy a theme instead of creating my own. But that requires me to find a theme first, and the theme to copy should be 'clean'.

Which leads to having a "library" of page structure recommendations / elements for common use cases / patterns. Boilerplates. Random examples:

Event Timeline

This task combines a number of very large related but not entirely overlapping chunks of work. For example:

  • Define and document steps to take and things to consider before creating a new doc
  • Define and document best practices for where to put docs and how to make your docs discoverable. This is partially covered by ongoing work on doc review processes: T310319.
  • Provide guidance for non-translate-experts on how to work with translated content
  • Provide templates and boilerplate for specific content types. Note: There is a library of templates here:
  • Define standards and requirements for Engineering team pages, and determine how to enforce them (templates may be one way) (T115853)
  • Define content requirements for what new extensions should include in Extension:Foo vs Help:Extension:Foo vs Manual:, and make it easy for developers to meet those requirements

Some of these items are partially covered by ongoing work on doc review processes: T310319, but when we do our planning for the coming quarters we'll create additional tasks to cover more of the above. I'm going to leave this task open for now, but I intend to file more specific individual tasks for the things outlined above. Once we decide how to divide up and organize the documentation work for FY22/23, I'll update this thread with the new, more focused tasks and then decline this task.

TBurmeister added a subscriber: apaskulin.

Work in the area of doc templates depends on the outcomes of research into information patterns being undertaken by @apaskulin for the coming quarter. There will not be specific phab tasks for this work because it is exploratory at this time. See https://www.mediawiki.org/wiki/Documentation/Patterns