Scope needed cleanup for API pages for Source Code
Problem to solve
October / November 2022 API work for groupsource code has made the engineering team realize the API pages for groupsource code are out of date, don't match our style guide for APIs, and frequently lack response sections.
The lack of response sections makes it difficult to document when groupsource code makes changes to the responses.
Further details
Proposal
We should …
-
Determine how we want to handle the reviews, and at what cadence. While Amy can polish existing information, she leans on the engineers in her groups to determine if information is outdated or wrong. -
Bonus points: do pairing sessions with Amy to help her extract more of this info from the API herself, without assistance. (Anyone need to burnish their mentoring skills?) -
Assess how many pages need review, and figure out the speed we want to work on these cleanups. -
Figure out how we want to track / assign the work. An epic with sub-issues? A single issue with tasks?
Who can address the issue
Other links/references
- Related to Introduce new detailed_merge_status to the API (#370856 - closed) where a new field (
detailed_merge_status) was introduced to the response of an API endpoint. - Related to Introduce new detailed_merge_status to the merg... (!101724 - merged) where the engineering work for
detailed_merge_statuswas merged, and I chose to start with an MVC of the table to get the docs fixes started. - Related to Follow-up from "Introduce new detailed_merge_st... (#379607 - closed) was my follow-up issue for doing more work to the docs page. !101724 (merged) had a long and painful road to merging, and it made more sense to iterate after merging.
- Related to Begin revisions of merge requests API page (!102566 - merged) where I began the follow-up work to polish the previously-added API response table, but elected to skip one extremely problematic subheading.
- Related to Clean up info about response data, place in table (!102782 - merged) where I began to garden in the items from the problematic subheading into the table now that it was cleaned up.
- TBD: the merge request where Amy works with the Support stable counterpart to determine what to do about that last item, which is gnarly enough that it may need to move elsewhere in the documentation.