← Documentation Team

Triage


  • Each week, we assign one team member to monitor #org-documentation and create a Jira Documentation Request (DR) for each submission.
  • If you’re on triage, it’s important to give these tasks priority in your day. This includes asking and/or searching for additional information.
    • As we reach out to a PR owner, it’s best practice that we communicate primarily within the PR. Tag the owner, and post your comments. Then ping the owner—via Slack—with a link to the PR. This helps keep our communication transparent and the team aware of progress made on a PR.
    • If a DR has been submitted, yet more information is needed before you begin a PR, we recommend tagging the submitter and posting your comments within the DR itself. Then ping the submitter—via Slack—with a link to the DR.
  • If a request looks quick and you can’t get to it, drop the card in #teams-doc and let others know there’s low hanging fruit to tackle.
    • Do this especially if it’s early in the week.
  • If you receive multiple, easy docs to work on, drop the info in #team-docs in case someone else has time to complete a DR before you get to it.

Knowledge Repo

  • Review all PRs in the Knowledge repo.
    • Move along, approve, and/or merge old PRs.
      • Sweep 2x per weekly rotation.
      • Tag the outstanding PR owners (and then ping) that are outside the doc team, if needed.
        • Address unresolved conversations.
        • Share with the owner that we’ll be merging the PR at the end of week.
      • If there’s a blocked PR, add a Blocked label so the team is aware and doesn’t have to continually review it.
  • If a PR is a Draft, you don’t have to review it.
    • If it’s an outstanding Draft PR (2+ weeks old), use your judgement if you should to tag and ping the PR owner.

Wiki Repo

  • Review all PRs in the Wiki repo.
    • Move along, approve, and/or merge old PRs.
      • Sweep 2x per weekly rotation.
      • Tag the outstanding PR owners (and then ping) that are outside the doc team, if needed.
        • Applies to PRs that are 2+ months olds.
        • Address unresolved conversations.
        • Share with the owner that we’ll be merging the PR at the end of week.
        • Include PR’s URL.
        • Script example: Hey! Is this PR still valid, or are you waiting on anything? If not, I’ll go ahead and close the PR by the end of the week. Thanks!
      • If there’s a blocked PR, add a Blocked label so the team’s aware and doesn’t have to continually review it.
  • If a PR is a Draft, you don’t have to review it.
    • If it’s an outstanding Draft PR (2+ weeks old), use your judgement if you should to tag and ping the PR owner.

Jira

Jira helps us prioritize requests and track our work. Cards for both the Knowledge-Base and Wiki are created on our team Kanban board.

  • Review unassigned On Deck cards and new/backlog issues to ensure they’re not stalled.
    • Sweep 2x per weekly rotation.
  • Create a card on the team board or request the reporter create a Documentation Request (DR) for each incoming item from #org-documentation.
    • Assess if the incoming request, content, or doc is valid before making a card on the team board. You’ll want to check for the following:
      • Completeness
      • Duplicate doc(s) or content that might exist
        • If there is still useful information, note that it’s an update in the card’s Summary.
          • Example: Update Account Details ops doc
      • Duplicate existing issue
        • If there’s an open issue for the request, tie that request to the existing issue and reevaluate its place in the Backlog/On Deck/Inbox list.
      • If an existing document is supplied, check if it needs major revision and note that in the issue:
        • Voice
        • Layout
        • Purpose - feel free to check with the team
    • If you determine the request is invalid, contact the requestor with details (ex. The first paragraph needs some additional information. What problem does this PowerOn solve? Where can implementation coordinators’s find the PowerOn?) and note the communication within the issue only.
      • Once all of the content is submitted or the questions are answered, you should create a card on the team board.
  • Most cards will likely go in the Inbox.
    • If the request shifts people from using a Google Doc, it should have a higher priority
    • Ops doc requests: Place the card at the top of On Deck.
    • Marketing doc requests: New document upload requests from Marketing—collateral such as Banno Feature List, Banno Due Diligence, etc.—should always be completed ASAP. If it seems easy enough to complete in a short time, go ahead and do so.
  • Completing DRs that are In Progress or Needs Review are the responsibility of the assignee.
  • If a DR looks out-of-date, please tag the assignee (also ping) and ask them to update the request—or status—if needed.

Slack

Team members across Banno use Slack to notify us of needed doc updates and to ask questions.

  • Answer or delegate answering questions asked in #org-documentation or pinged in other channels.
  • Make sure people use the @documentation team ping or #org-documentation.
    • Unless they’ve asked you about it before.
    • Answer if you can, or post the question in #team-docs if you can’t.
  • When a slack conversation is noted with documentation-team reaction, the link displays in our #org-documentation channel.
    • Review the Slack thread and follow the process for creating a card in Jira.
      • In the card, include the Slack link.
    • Let the OP know you’ve created an issue and it’s in the doc team workflow.
      • We appreciate you notifying the doc team! I’ve created an issue, and it’s in our workflow. If you or anyone else needs to review the doc or be notified when it’s done, please submit a Documentation Request.

Google Analytics

We post quarterly updates on how and when users engage with the Knowledge Base. We like to know our high-traffic days and the causes for increased traffic, so you can check #org-customer-communication or ask in other channels if something went out with links to the Knowledge Base. Typical customer communication could include a Banno Statement, announcement to customers via email, etc. Once you know, please share the deets with Brittany McNamara so she can include them in the quarterly report.

Workflow Example

Monday

  • During the Jira sweep, discuss previous week’s triage requests and/or issues with the team.
  • Review all PRs in a Github sweep.
  • Move along, approve, and/or merge old Wiki PRs.
  • Review Google analytics from the previous week. Note high traffic days and track down the reason for increased page views. Let Brittany McNamara know the details for the quarterly report.

Tuesday

  • Review unassigned On Deck cards and new/backlog issues to ensure they’re not stalled.
  • If a DR looks out-of-date, tag and ping the assignee to update the request.

Wednesday

  • Review all PRs in a Github sweep.
  • Move along, approve, and/or merge old Wiki PRs.

Thursday

  • Review unassigned On Deck cards and new/backlog issues to ensure they’re not stalled.

Friday

  • Last day to respond to owner(s) or reviewer(s) in cards
  • Note anything to share at next week’s Jira sweep on Monday morning.