Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

IA Guide - future edits #167

Open
Loquacity opened this issue Nov 15, 2020 · 0 comments
Open

IA Guide - future edits #167

Loquacity opened this issue Nov 15, 2020 · 0 comments
Labels
IA-Guide For issues relating to the Information Architecture Guide improve For any suggestions about how to make templates better.

Comments

@Loquacity
Copy link
Member

Loquacity commented Nov 15, 2020

When the IA Guide hits the website, these are the next things to be worked on:

  • Set the objective or expectation more clearly -- what is it I want my audience after reading this document to walk-away understanding. And I think this idea of State Your Intent captures it. I think it may belong higher up in the narrative.
  • Expand on the 'Prepare to Adjust' section. I like the idea of maybe closing with the process of planning like in 'Measure The Distance'
  • Group 'Choose a Direction' into a larger Planning piece to work with 'Measure the distance'.
  • In 'Identify the Mess' suggest looking at Pull Requests and Issue-Trackers on github.
  • Static version only: In Critical Paths table, actually fill out the table with a real example -- just the first 3-4 rows. And we can create/link to an empty template version that someone could download/clone, or use the tag to hide and collapse an empty version
  • Move instructions for Critical Paths table above the fold.
  • In Toaster/Car/Nuclear reactor sections, specific types of docs one would expect.
    • Toaster:
      • One-Page Reference card indicating the parts of the toaster
      • Reverse-Side details on how to use the toaster safely
    • Car:
      • A large-leather bound reference volume with complete user-instructions on every aspect of the vehicle functions and specifications (Interior & Exterior).
      • ... are there other docs that come with a car? There might be additional manufacturing documents provided to Car Retailers and Auto-Mechanics that aren't available to customers.
    • Nuclear reactor:
      • I guarantee there are 3-ring binders complete with operational How-Tos / Runbooks on how to Triage and Resolve monitoring errors/warnings happening across the various system.
      • There are probably documented policies on what to do when certain alerts/warnings happen -- some may even have legal requirements in term of reporting them to government agencies.
      • Not to mention the outstanding Reference documents.
  • In 'Writing for Readers', add a doc-type to the table to correspond with some of the templates we are promoting from the good-docs/templates.

Collected from thegooddocsproject/incubator#13

@Loquacity Loquacity added IA-Guide For issues relating to the Information Architecture Guide improve For any suggestions about how to make templates better. labels Nov 15, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
IA-Guide For issues relating to the Information Architecture Guide improve For any suggestions about how to make templates better.
Projects
None yet
Development

No branches or pull requests

1 participant