Jump to content

Documentation/Review template/Technical decision forum

From mediawiki.org

Page: Technical Decision Forum

Style review

[edit]

Review the style of the page for compliance with the Wikimedia technical documentation style guide.

Plain language

[edit]

Use a writing analysis tool (like Expresso) to get metrics on sentence length, grade level, and other aspects of plain language. Here are a few metrics key metrics to review.

A note about Expresso: Expresso takes pasted text as an input, so you may need to analyze text at the paragraph or section level.
Metric Goal Notes
Grade level Grade level of 8 or lower. Note that specialized terms like "Wikimedia" may inflate grade level scores.
Sentence length Sentences are not more than 30 words in length.
Negations Avoid using negative sentence constructions.
Active voice Use active voice, except when diplomacy calls for passive voice.
Second person point of view Use second person ("You" or assumed "You") when addressing your audience. Avoid first person ("I"), unless the page is an FAQ with questions asked from the first person perspective.
Imperative mood Uses an imperative mood for most documentation focused on goals or process.

Inclusive language

[edit]

Use non-gendered language, and avoid the terms listed in the inclusive language guide, jargon, idioms, and other ambiguous or confusing elements.

Content review

[edit]

What is the topic of the page?

  • The process for making technical decisions at the Wikimedia Foundation

Does the page fit into to a defined content type?

  • The first three sections are a landing page
  • The last three are part explanation, part directory

What information is included on the page?

  • Link to updates and update template
  • Link to decision records
  • Link to the explanation of the process
  • Link to FAQs
  • Email contact
  • Forum chair role description, process, and current chairs
  • Forum member role description, process, current members and team contacts

Who is the audience (or audiences) of the page? Is the content of the page suitable for that audience?

  • People who are involved in the forum
  • People who are interested in a decision

Are there any duplicate pages that need to be merged or marked as obsolete?

  • Leftover cleanup from TechCom

How is the page linked to related pages? Is it part of a clearly defined collection of pages? Check Special:PrefixIndex for subpages.

What are the most impactful changes that can be made to improve the collection?

  • Move updates to a talk page
  • Create a consistent navigation element across subpages

Checklist for all pages

[edit]
  • {{{2}}} Title style: Uses sentence case for titles. The title should be descriptive and specific. This helps visitors decide whether they would want to use the page. For example: "Accessing Instances on Cloud VPS" is much better than "Instances".
  • {{{2}}} Introduction: For search optimization and page previews, include a short introduction as the first text on the page following the title. This should briefly introduce the content type, purpose of the page, general audience, and topic with the goal of providing enough information to be meaningful in a set of search results.
  • {{{2}}} Table of contents: MediaWiki automatically creates a table of contents when a page has more than three headings.[1] Use template:TOC to limit the heading levels displayed in the table of contents so that it is meaningful and concise. To save space, a table of contents can be opposite the title (right-aligned in LTR languages).
  • {{{2}}} Section headings: Section headings use sentence case. Headings should use h2, h3, and h4 styles.
  • {{{2}}} Code samples: Code samples should use template:Codesample and include a filename if appropriate.
  • {{{2}}} Links: Links on the page go to existing, non-obsolete pages (unless for historical reasons). Link text is descriptive and does not include any wiki prefixes. Special:MyLanguage links are used whenever possible.
  • {{{2}}} Lists: Do not use bulleted list items to complete an introductory sentence fragment.
  • {{{2}}} Status: No draft or outdated banners are present.
  • {{{2}}} Feedback and communication: The page prompts readers to share feedback or ask a question. It indicates where readers can go to get updates or connect with others, if appropriate. A talk page exists (or redirects to a central talk page) with at least a welcome post.
  • {{{2}}} Translation: If translation is available and the content of the page is stable, the page is marked for translation.
  • {{{2}}} Mobile: The page is readable on mobile, with all important information visible.
  • {{{2}}} Accessibility: The page complies with the accessibility guide for developers.
  • {{{2}}} Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).

Checklist for landing pages

[edit]
  • {{{2}}} Descriptive title: Because landing pages help organize and contextualize other pages, the title of a landing page should be descriptive enough to make sense when viewed directly from a search engine.
  • {{{2}}} Image: If possible, include an image relevant to the topic, such as a project logo. The image can be centered or aligned opposite the title (right-aligned in LTR languages) using [[File:Example|{{dir|{{pagelang}}|left|right}}|30x30px]][2].
  • {{{2}}} Topic overview: To provide context, a landing page should include a section that introduces the topic or theme of the page. For example, a landing page for Toolforge should include a section that describes what Toolforge is, what is does, and who uses it. This can be under an "About Toolforge" section or, if it makes sense with the layout of the page, in the first section under the title.
  • {{{2}}} Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.[3]
  • {{{2}}} Link hub layout: When linking to other documentation pages, present groups of links in a way that is easy to navigate, such as Template:ContentGrid, Template:Colored box, Template:Contribution, Template:Portal list item on Wikitech, or a sidebar. Avoid organizing links with tables or headings.
  • {{{2}}} Maintainer resources: Landing pages help facilitate the maintenance of a set of documentation. If possible, include ways for people to participate by subscribing to updates, watching pages, joining editathons, etc. Be explicit about which pages to watch to help answer questions and monitor edits.
  • {{{2}}} Navigation between subpages: A landing page should include a navigation element that allows readers to move between pages within the collection, such as a sidebar, navigation box, or set of tabs. If the collection is organized using subpages, include a prefix search box.

Maintainer outreach

[edit]

Is there anything notable in the recent activity? Check page views, talk page posts, and recent edits.

Who seems to be active on or knowledgeable about the page?

  • ...
  1. ↑ Manual:Table_of_contents
  2. ↑ Template:Pagelang
  3. ↑ https://www.livescience.com/2493-mind-limit-4.html
Retrieved from "https://www.mediawiki.org/w/index.php?title=Documentation/Review_template/Technical_decision_forum&oldid=6351511"