Page MenuHomePhabricator

Create new content and structure for requestctl tool documentation
Closed, ResolvedPublic

Description

Main goals for requestctl documentation improvements:

  • Docs should be more audience-focused, so they're more accessible to different types of users (new SRE, active SRE, admin)
  • Docs should be more concise and succinct: use writing style and structure focused on optimizing UX for readers under pressure
  • Docs should contain updated links to/from relevant resources like playbooks and code repos

This work is broken down into 3 pieces, in order of priority (highest to lowest):

  • p0 - Create an outline of a task-focused document that emphasizes examples and contains how-to instructions and a quick reference. Audience: SREs who are using the tool during an outage
  • p1 - Create an outline of a conceptual overview and tutorials to help readers learn how to use the tool, understand its purpose, get comfortable with its functionality, and understand the object model. Audience: SREs who are onboarding or new to using the tool.
  • p2 - Create an outline of a task-focused document that covers administrative work like submitting patches or performing other tool maintainance tasks. Audience: Engineers/admins who maintain the requestctl tool.

Event Timeline

TBurmeister triaged this task as Medium priority.
TBurmeister updated the task description. (Show Details)
TBurmeister moved this task from Backlog to Next on the Tech-Docs-Team board.

Status update:

I ended up working on the improving the content and style of these docs, not just their structure. I just couldn't effectively work on the structure without understanding more of the content, and I couldn't resist improving the content when I was reading it for understanding. So! the scope of this task is slightly larger than originally defined, but the improvements are already underway and it'll be easier for @CDanis or whoever the final subject matter expert reviewer/writer is to fill in the gaps.

Items still TODO, some of which may require consultation:

  • There are many TODOs in the drafts, some of which I will resolve but others will require SMEs to fix.
  • I'm not sure we'll end up keeping the layout grid for providing navigation between these 3 pages. For the user guide, tutorial, and reference content, I've chosen (for now) to do a single-page model, which is best for ctrl+f and panicked on-call searching, but may not be the best overall since the TOC and page are already quite long. The tutorial can be moved elsewhere if the user guide covers all the tasks and commands that were previously only covered by the tutorial.
  • To build out this content, I copied everything from the README and integrated it with the content that was on the wiki page. We need to decide where we want the content to live, and implement the necessary cross-references (right now the drafts are duplicating content that is in the README).
  • There are multiple developer tasks and pieces of information I identified during the research phase of this project; we still need to add those to the pages, and compare the content of the DDoS playbook to check for coverage of content there vs in these docs.
  • Need to clarify what the intended functionality of the web app / new requestctl UI (T371782) will be, and how that impacts what the docs need to cover.

Assigning this task to Joe for content review of the draft at https://wikitech.wikimedia.org/wiki/User:Triciaburmeister/Sandbox/requestctl, including specific clarifying questions marked with TODO in the text. Note: this work may be delayed due to ongoing work on the new UI, since we want the docs to align with and function alongside that new tool.

TBurmeister updated the task description. (Show Details)
TBurmeister updated the task description. (Show Details)

Thanks to @Joe for work on building out the tutorial content for haproxy actions, and addressing various TODOs from my first drafts. I have finished revising, copy-editing, and cleanup of both:

We agreed to move the tutorial content into its own page because there was too much: https://wikitech.wikimedia.org/wiki/Requestctl/Tutorials. I will review and copy-edit that tomorrow, and plan to move the user guide from my sandbox to the mainspace at https://wikitech.wikimedia.org/wiki/Requestctl tomorrow or on Monday.

TBurmeister renamed this task from Create new content structure for requestctl tool documentation to Create new content and structure for requestctl tool documentation.Oct 24 2024, 9:02 PM
TBurmeister changed the task status from Open to In Progress.

Revised and expanded doc is published at https://wikitech.wikimedia.org/wiki/Requestctl.

Resolving this task even though the p2 sub-task is unfinished, since I don't think any Admin docs exist yet.