Establish subset(s) of the team responsible for style and linting
The problem
Style standards and linting (and other testing) are increasingly important as we seek to produce consistent, high-quality docs from a wide array of authors. However, a lack of process in these areas has led many efforts to too wide of a discussion before moving forward, or proceed without sufficient review and coordination. For example, with linting rules, we need to take care to ensure that they are backed by a documented style, when possible, that they work as intended, and that they offer a good experience for doc authors and reviewers.
Committees
TW Style Committee
- Areas of coverage
- Documentation Style Guide
- Pajamas Content section (for GitLab UI text standards)
- Release Post and technical blog post content standards
- Tasks
- Review MRs with tw-style label
- Proactive projects
- Add further parity between styles and linting (proposing work to be done by linting DRIs)
- Audit styles and for each, specify whether a linting rule exists, should be created, or is not practical/applicable.
- Maintain a single source of truth with standards for cross referencing any given style and linting rule
- Review the style guide to make it more consistent and easy to use.
- Share updates to the Style Guide.
- Add further parity between styles and linting (proposing work to be done by linting DRIs)
- Manage proposals about
- Existing styles
- Conflicting styles across guides
- Watch #docs-style and help with style questions.
- Members and roles
- 1 DRI (Mike L)
- Maintain board / triage issues and help ensure issues/MRs move to resolution.
- Raise process/policy improvements for review by TW leadership team.
- 3 rotating (every 4 months, but begin to stagger changes so not all change at once)
- Suzanne, Mike J, Marcia - ideas for who might be good as inaugural members, per their experience and based on a discussion with @susantacker, but they’re welcome to defer to others -- not set in stone.
- 1 DRI (Mike L)
TW Test Automation Committee
- Areas of coverage
- Content linting in documentation and UI
- Vale
- Markdownlint
- UI app/views linting
- Other related testing
- Nanoc tests (e.g. external links checker)
- lint-doc.sh (e.g. checking file permissions, preventing new README.md files)
- Any future doc site rendering tests e.g. Selenium
- Content linting in documentation and UI
- Tasks
- Implement linting issues, driven by style changes or with accompanying style change proposals, where applicable.
- Review MRs with tw-testing label.
- Members and roles
- Marcel as DRI; Evan, Amy. (Note: No pre-planned rotation due to the existing expertise, but all are welcome to contribute to MRs/discussions, learn more about the process, and propose further responsibility.)
- Member responsibilities
- DRI must approve:
- Any new rule. (Also to get manager approval for whole new linter in CI and anything else you think needs it.)
- Any new or changed regex in a rule.
- For Vale, Amy must also approve any new rule (i.e. a new YML file).
- Any member must review or approve a change/addition to a rule.
- DRI will also
- Maintain board / triage issues and help ensure issues/MRs move to resolution.
- Raise process/policy improvements for review by TW leadership team.
- DRI must approve:
Details to document
Interaction of Style and Linting
- Styles and linting rules often go hand-in-hand. There are also styles that can’t (or don’t yet) have a rule, like voice recommendations, or there will be linting work that doesn’t map back to a style, like finding malformed URLs.
- Anyone can contribute:
- Start a discussion in #docs-style or #docs-linting
- Raise an MR using the labels
tw-style
ortw-testing
. Use both if both are affected. - Or open an issue using the labels
tw-style
ortw-linting
. Clarify if it’s a question, idea, problem/bug, or proposal. - Note that these labels don’t begin with “docs”, because we also want to include UI text and other contexts like the Release Post.
Other Changes needed
- Updates in https://docs.gitlab.com/ee/development/documentation/#testing
- Clarification of committees in Handbook
- Roles
- Dealing with MR
- When to get +1s
- When to have DRI
- When to have managers
- When to include other committee
- How to communicate it (Zapier to Slack?)
- Recurring jobs for each DRI
- Recurring jobs for all
- Monitor Slack
- Call every 2 weeks?
- codeowners - all of each committee become codeowners, committee members know to get additional approvals if it’s a proposal.
- Special merge requirements for new tests (managers), new yml (must include dri)
- Roulette
- Templates
- Style change
- Summary
- Background (links to good or bad usage, links to prior discussions)
- Linting change required? (If yes, then do one of the following and assign the mentioned issue/MR to a linting committee member in addition to the style committee member.)
- Include in this MR and add linting label
- Link linting issue
- Link linting MR
- Linting change
- Summary
- Background (links to good or bad usage, links to prior discussions)
- Style change required/included? Updating a rule to further interpret a style?
- If also a style change, ensure it’s included in the same MR. (Don’t implement a linting rule without a style, if a style would be relevant. Updating a rule is OK.)
- If further interpreting a style (e.g. adding an allowed acronym) then consider this to also be a style MR (use required label and approver(s))
- Style change
Prior issue description stored below.
Handle issues around The GitLab Documentation Style Guide, Pajamas Content guidelines, Linting.
Problem to solve
Style and linting are very helpful to authors and reviewers, enabling them to merge better content more easily.
However, we need to ensure consistency in how we handle style considerations without commanding the time and attention of the majority of the Technical Writing team for each issue/MR that arises.
Jobs to be done:
- Style
- Areas of focus include the GitLab Documentation Style Guide, use of fallback styles (from other guides), alignment with Pajamas and other company styles, alignment with docs linting.
- Address style questions, proposals, and MRs.
- Iterate on process as it relates to style and linting
- Triage of style issues and MR reviews
- Ensure consistency across Pajamas and Docs guides - clarity on shared vs not-shared styles
- Manage a board of style issues
- Manage proposals about
- Existing styles
- Fallback styles
- Pajamas vs doc style
- Linting vs. style parity
- Proactive projects
- Add further parity between styles and linting (proposing work to be done by linting DRIs)
- Audit styles and for each, specify whether a linting rule exists, should be created, or is not practical/applicable.
- Maintain a single source of truth with standards for cross referencing any given style and linting rule
- Review the style guide to make it more consistent and easy to use.
- Share updates to the Style Guide.
- Add further parity between styles and linting (proposing work to be done by linting DRIs)
Structure
- Members
- 1 TW DRI responsible for triaging issues and helping ensure they move to resolution.
- 3 additional TW members. This group will change quarterly.
- Specific group of CODEOWNERS for
- the Documentation Style Guide
- the Pajamas "Content" section (e.g. Error Messages) as discussed in gitlab-org/gitlab-services/design.gitlab.com!1709 (merged) (merged)
- Attempt to resolve style questions on their own, but to take some items to the team when unsure -- and of course continue to encourage everyone to raise style questions. Can poll the team, escalate to management, etc.
- Monitor #docs-style, whereas this could be optional for everyone else on the team.
- Issue board/labels (stemming from types of issues).
- doc-style::question
- doc-style::proposal
- doc-style::project
- doc-style::linting-exception
- doc-style::ongoing (e.g. communicate changes regularly in #docs)
- be a primary source of linting requests which will have their own issues and DRIs
- doc-linting::bug
- doc-linting::new, etc
Process for style proposals
Questions/todo
- Should we include UX and how? (Can discuss with Taurie.) Ensure compatibility with broader Pajamas processes.
- SSOT for styles in Pajamas and Documentation guides