This task is part of a project to establish a formal review process and set of standards for Wikimedia technical documentation. For more information, visit the project page on mediawiki.org

What to do

You're the lucky recipient of this task for which Sarah had already created some staged changes and done some review. (see below). Your task is thus:

1. Review the staged changes. Follow the doc review process Option B, but do the review for the staged draft of the page.
2. Complete the content and style checklists below to make sure the staged changes follow the guidelines.
3. Check with the page maintainer(s) to confirm that the changes should be implemented.
4. Implement the changes! Follow the guidelines here for when to mark the page as "work in progress" and ready for translation.

Original page

https://wikitech.wikimedia.org/wiki/Help:Toolforge/Developing_successful_tools

Staged version of page to review

https://wikitech.wikimedia.org/wiki/User:SRodlund/developing_successful_tools_(staging)

Content review (done)

What is the topic of the page?

• This page provides tips to help you develop successful tools on Toolforge. If you have useful advice share here!

Does the page fit into to a defined content type?

• Not sure. Probably an Explanation page.

What information is included on the page?

It contains information on building a successful toolforge tool.
The page opens with a one-sheet graphic with development tips. The page goes into greater detail about the tips outlined in the graphic.

• This page is a list of tips about development practices. There is a lot of random and scattered information here.
• Pick a license
• Publish the code
• Have co-maintainers
• Write some docs
• Going beyond
• Planning for success - Info about setting up an account
• Include useful links on a tool's public webpage
• Communication and support

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

• The audience is both newer and existing contributors. The content is suitable. It has information on steps to take in developing a successful tool.

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

• I imagine that most of this information can be found elsewhere in the Toolforge collection, and that this page serves more as a place to collect tips about common issues that come up for newer users, rather than a place for substantive instruction or information.

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

• Note that this page is linked to from the special Toolforge Navigation box -- so it appears on about 60 pages in the Toolforge collection.

What are the most impactful changes that can be made to improve the page? If the page is part of a collection, what are the most impactful changes that can be made to improve the collection as a whole?

• There are 3 directions for this page 1) Leave the page almost as is, with some changes to fit accuracy criteria 2) Make the page obsolete, as the information is surely in other places on Toolforge 3) A rewrite of this page to serve a more specific purpose.

On first glance it's difficult to decide who the audience here and why the choices were made to include and design the information on this page.

Spoke with maintainer to discuss needs for this page and agreed to retain content and add more context.

Content checklist (Done)

• 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.
• 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).
• Section headings: Section headings use sentence case. Headings should use h2, h3, and h4 styles.
• Code samples: Code samples should use template:Codesample and include a filename if appropriate.
• 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.
• Lists: Do not use bulleted list items to complete an introductory sentence fragment.
• Status: No draft or outdated banners are present.
• Translation: If translation is available and the content of the page is stable, the page is marked for translation.
• Mobile: The page is readable on mobile, with all important information visible.
• Accessibility: The page complies with the accessibility guide for developers.
• Date format: Either write out the complete date (September 1, 2021) or use YYYY-MM-DD format (2021-09-01).
• 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.
• 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 it 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.
• Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.
• 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.

Maintainer outreach (Done)

Is there anything notable in the recent activity? Check page views, talk page posts, and recent edits.
No. Since this is a staged doc, I've been the only with any activity on the page.

Who seems to be active on or knowledgeable about the page?
The WMCS team. Example: Bryan Davids

To reach out to

To discuss with maintainers

• 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".
• 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.
• Friendlier language for newcomers: Adding a section that provides quick links and some friendly, task-based descriptions

Writing style review (Done)

Review the style of the page for compliance with the [[Documentation/Style guide|Wikimedia technical documentation style guide]]. Using a writing analysis tool (like [https://www.expresso-app.org/ Expresso]) can help you identify ways to improve readability, sentence length, and other aspects of plain language.

• Plain language: The language used on the page is clear and concise. It is free of jargon, idioms, and other ambiguous or confusing elements. Sentences are not more than 30 words in length.
• Positive language: Avoid using negative sentence constructions.
• Inclusive language: Use non-gendered language, and avoid the terms listed in the inclusive language guide.
• Active voice: Use active voice, except when diplomacy calls for passive voice.
• Second person point of view: Uses second person ("You" or assumed "You") when addressing your audience. Avoid first person ("I", "we", "our"), 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. Avoid future tense ("will").
• Typos: The page has been reviewed for typos.
• (Optional) Grade level check: Use a writing analysis tool (like Expresso) to check the grade level of the page (sometimes called a readability score). Strive to keep documentation under an eighth grade reading level.