facebookarchive/prepack

"Refactor" how we maintain documentation on PPxxxx diagnostics codes

Open

#2440 opened on Aug 17, 2018

View on GitHub
 (1 comment) (0 reactions) (0 assignees)JavaScript (14,268 stars) (520 forks)batch import
help wantedrefactoringwebsite

Description

We currently issue new PPxxxx numbers ad hoc, and maintain wiki pages for them. This is problematic for a number of reasons:

  • Wiki pages cannot be edited by the general public, but only Prepack team members
  • There's a race when issuing new PPxxxx numbers, as the PRs are disconnected from editing wiki pages
  • As a result, discrepancies have crept in in the past, see e.g. #2439

Proposal:

  • Migrate all PPxxxx wiki pages to files in a new directory website/diagnostics/en-US
  • Have a new file website/diagnostics.html which links to all the individual diagnostics issues
  • Consider generating this file with some script that can be run from the scripts/publish-gh-pages.sh script
  • Use some on-the-fly markdown processor in JavaScript to render the individual files in the website/diagnostics directory
  • (Nice to have) write some kind of linter that ensures that every mention of PPxxxx has an associated file in the website/diagnostics directory

Advantages:

  • Races/conflicts between allocating the same new PPxxxx number will be detected before a PR can land
  • Diagnostics help text will get reviewed as part of a PR
  • Non-prepack team members can contribute diagnostics help
  • It will be way easier to ensure that PPxxxx actually have documentation (ideally in an automated fashion with some kind of linter)

Contributor guide

Tech stack
javascripthtml
Domain
documentationtooling
Issue type
refactor
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
4
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
3-5 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
JavaScriptMarkdownPrepack's documentation conventions
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
35
Research direction
Examine the existing wiki pages for PPxxxx codes to understand current formatting. Review the project's website generation scripts (scripts/publish gh pages.sh) to understand how the site is built. Propose a design for the new website/diagnostics.html and the markdown rendering process. Consider implementing a linter as described.