Summary

In doing research for Infra Dashboard I've found that among the biggest common requests have been:

  • navigating our documentation
  • providing an central organized launchpad to our various tools.

Re-arranging the index page will reduce the need for a dashboard by presenting our documentation in a more refined and compact, service oriented format and the infra-doctype  tags will give us better relevance in our documentation cross sections.

Re-arranged index page will also include a navigation pane populated with a curated list of links to our various tools.

Things Implemented:

  • infra-doctype  tags to track / organize:
    • Policy documents
    • Project management pages
    • Administration / Process pages
    • Configuration documents
    • Runbooks / Troubleshooting documentation
    • Notes and internal conversation documentation
  •  infra-review tag to keep documentation updates and organization rolling.

Questions:

  • Should we have an infra-service umbrella tag instead of labeling service related documentation with the name of the service directly e.g. infra-mail?
    • Andrew: I THINK the labels are universal for our instance of the wiki, so any other space can use a tag like "mail" (and can also delete it, I think). I thought that's why we were using the infra-X formulation.
  • Would we have an internals or tlp-service (or something of the like)  tag to differentiate ASF services versus TLP services?
    • Andrew: That's covered by the access permissions. You only see what you have permission to see. For indexing, that's why I thought of putting them in two stacks.
    • Drew: That's fair. I was under the impression that we're trying to push infra.a.o as the point of entry for project facing documentation. That would leave the INFRA:Index to us (more or less)

Goals:

  • Make access to relevant documentation more streamlined
    • Better, more relevant document tagging means better at-a-glance 
  • Some hi-vis project management in the form of the infra-doctype-project  label
    • easily list all of the ongoing projects and their associated tasks

Index top-level categories

CurrentProposed
On-call and pager duty
Infra project management
Infra Monitoring and Incident response
Infra Policies
Services
Machines and VMs
Processes
Other
Archived pages

On-call and pager duty
Jira
Infra projects
Monitoring and Incident response
Machines and VMs
Processes
ASF services
TLP services
Policies
Other
Archive


Services category proposed subcategories

I like the logical groupings proposed however I think we should use confluence label queries to define them on the homepage and then just update the query as needs change.


Currently I've got the following set up as ASF services and TLP services

Email
Jenkins CI
Buildbot CI
Jira / Bugzilla
Confluence
Automation
LDAP and accounts
Content Distribution
Git / Github
Subversion
Machines
Security
Miscellany

CurrentProposed "ASF Services"Proposed "TLP Services"
ASF accounts
Backups
Bug tracking
CI/CD
Confluence Wiki
Content distribution
DNS
Email
Jira (to become top-level category)
Slack
LDAP
Localization
Puppet
Security
Version control
Website tools

LDAP and ASF accounts
DNS
Slack
Puppet
Security

Backups
Bug tracking
CI/CD
Confluence Wiki
Content distribution
Email
Localization
Version control
Website tools (Combined with content distribution)

Proposed documentation categories – IMPLEMENTED

  • Administration (infra-doctype-admin)
    • process based documentation with how-to's and general overviews
  • Configuration (infra-doctype-config)
    • Flow diagrams and solution maps
    • Installation and setup documentation
  • Runbook (infra-doctype-runbook)
    • Troubleshooting documentation for the on call person
  • Policy (infra-doctype-policy)
    • self explanatory
  • Project Management (infra-doctype-project)
    • project management pages should be tagged with their respective service
    • can be navigated by anyone and should be targeted at infra.
  • Notes (infra-doctype-notes)
    • largely informal
    • primarily for internal consumption
    • good for discussion documents

Proposed 'infra-review' label – IMPLEMENTED

To encourage a "living documentation" I'd like to add an infra-review tag that is used to flag articles for discussion in the same way that the 'Review Date' field flags Jira tickets for discussion.

Current Labels