Perhaps related: https://phabricator.wikimedia.org/T1287

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

Page

https://www.mediawiki.org/wiki/Architecture_Repository

Content review

What is the topic of the page?

• When I first arrive on the page, I am unsure. It initially appears to be an overview of technical architecture or system infrastructure (like many of the docs mentioned in https://phabricator.wikimedia.org/T1287), but then it seems to describe a team and its members and goals, and then it offers many links to best practices and a large repository of content around "architecture" topics.

After reading some of the docs in this collection, the topic of this page seems to be an initiative involving team support and advising along with lots of informational resources and perhaps conventions around how system architecture should be built and evolved.

Does the page fit into to a defined content type?

• Cross-collection landing page, currently seems to be acting as a landing page for what could be multiple collections.

What information is included on the page?

• There are at least six different navigation elements on the page.
  • Top of page nav template (Template:Architecture Repository): links to the major sections of content grouped into "Practice | Strategy | Domain | Systems | Components"
  • Large diagram with linked text that includes the aforementioned sections but includes subsections beneath each of those. There are arrows between the nodes in the diagram, so at first glance (and given the title of the page) it reads as a system diagram. It takes a minute to realize that this is actually providing an overview of the content structure and how one might want to navigate through it.
  • "Exploring this repository" section: contains user task-focused links like "I want to...do xyz thing". Unclear at this point if these links duplicate the targets of other links and this is just trying to provide a more user-centric way of entering the content.
  • "Architecture practice" section: contains links to 6 out of the 7 items that appear under the "Practice" section in the large diagram.
  • "Core team": sidescrolling widget with links to team member pages
  • "Capabilities" section: links to 6 subpages. Most of them appear to be drafts with no content. The page that gathers these together is linked in the large diagram under "Domain" as "Capabilities".
  • Index: a large list of links for all the pages in this collection (those with the prefix 'Architecture Repository').

• The main pieces of non-navigational content are the Mission and Architecture Practice sections, which contain single paragraphs about what the team does / what the goal of this content is.

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

• Unclear from this page. From reading other pages, I gleaned that the audience is likely engineers and product teams, but it's unclear if the audience might include volunteer developers or only WMF staff, and to what degree this content would be useful to an IC vs. a tech lead or someone who makes decisions that then impact multiple teams or engineers.

Are there any duplicate pages or overlapping content that needs to be merged or marked as obsolete?

• Not that I could find

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

• See above re: navigation elements.

Content checklist

• Title style & Descriptive title: Current title doesn't make it clear what the page is and why I would read it. It doesn't use sentence case.
• Introduction: missing
• Topic overview: the Mission section sort of provides this, but it is far down the page for an overview. There is an 'About' page as well, but it is about maintaining the repo, not the goal or purpose of the repo.
• Table of contents: missing, but given the other navigation elements on the page, that is okay.
• Section headings: The first section heading doesn't use sentence case but the rest do.
• Links:
  • TODO: Some links on the page go to mostly empty pages.
  • OK: Link text is descriptive and does not include any wiki prefixes.
  • TODO: Doesn't use Special:MyLanguage links.
• Lists: The page has a couple instances of using bulleted list items to complete an introductory sentence fragment.
• Status: No draft or outdated banners are present.
• 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.
  • The links to team member pages could be interpreted as an invitation to communicate, but that should be more explicitly welcomed. Other pages mention how to contact the team via email, and there is one link to a talk page at the very bottom of the index.
• Translation: Translations aren't available and the page doesn't appear to ever have been marked for translation.
• Mobile: The large diagram is not readable on mobile: it requires side scrolling and the text within a node is split into two lines in some cases.
• Accessibility: The page complies with the accessibility guide for developers. (You can use the WAVE tool to check for critical issues.)
• Date format: n/a
• Image: diagrams and pictures of team members, but no image that signifies the topic or collection.
• Maintainer resources: The "about" page provides instructions and tools for contributing to and maintaining content in this collection.

Leaving the following items blank on purpose because navigational elements are the biggest part of this page and also likely to be what needs to change:

• 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.
• Small groups: When linking to other documentation pages, a landing page should organize links into groups of no more than six.[3]
• 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.

Recommendations

In addition to addressing any outstanding items in the checklist, 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?

• Audience focus and provide an intro to orient the reader to what the collection is about and what they can do with the info
• Remove the large navigational diagram and replace it with a link hub format that renders better on mobile
• Consider whether there are ways to integrate all the content linked in the various sections of the page into one link hub layout so that there are fewer lists of links on the page.
• Move the team info to a subpage
• Remove pages that don't contain any content and remove the links to them from the landing page

Maintainer outreach

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?

• ...

Do the recommendations from this review include changes to the page title or other significant content changes and should be discussed with a maintainer?

• ...

Writing style review

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.

Thanks for this review, @TBurmeister! These are all great points. After some discussion, I think that while the Architecture pages have a lot of potential, they are still in development and are not yet at the level where we can link to them in the Portal. I propose resolving this review task and removing this page from the Portal for now. In the future, if we accumulate more content in the Architecture Repository, we can address the recommendations made in this review.

• Audience focus and provide an intro to orient the reader to what the collection is about and what they can do with the info

The "Exploring this repository" section is attempting to do this, so I think some improvements to that section and maybe a more general intro would help with this.

• Remove the large navigational diagram and replace it with a link hub format that renders better on mobile
• Consider whether there are ways to integrate all the content linked in the various sections of the page into one link hub layout so that there are fewer lists of links on the page.

I'm definitely open to alternatives to the way the links are currently presented on the page. I was skeptical about the navigational diagram initially, but I've found it to be a useful tool for me personally.

• Remove pages that don't contain any content and remove the links to them from the landing page

When we set up these pages, we intentionally created a lot of placeholder pages that have unfortunately remained blank. I often struggle to remember and navigate to those pages that do contain content, so I think there is definitely some room for improvement here, but this feeds into larger questions about the purpose and use of these pages.

• Move the team info to a subpage

Since this info is so short, I'm not sure that it warrants its own page.

Change 763265 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[wikimedia/developer-portal@main] content: Remove link to architecture repository page

https://gerrit.wikimedia.org/r/763265

Change 763265 merged by jenkins-bot:

[wikimedia/developer-portal@main] content: Remove link to architecture repository page

https://gerrit.wikimedia.org/r/763265

Change 771364 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[wikimedia/developer-portal@main] content: Remove architecture repository content

https://gerrit.wikimedia.org/r/771364

Change 771364 abandoned by Triciaburmeister:

[wikimedia/developer-portal@main] content: Remove architecture repository content

Reason:

this is a messed up commit

https://gerrit.wikimedia.org/r/771364

Change 771364 restored by Triciaburmeister:

[wikimedia/developer-portal@main] content: Remove architecture repository content

https://gerrit.wikimedia.org/r/771364

Change 771364 abandoned by Triciaburmeister:

[wikimedia/developer-portal@main] content: Remove architecture repository content

Reason:

This was a mistake, these changes were merged in https://gerrit.wikimedia.org/r/c/wikimedia/developer-portal/+/771365/3

https://gerrit.wikimedia.org/r/771364