Content Planning and Coordination

Overview

This guide covers the sprint planning and coordination processes, focusing on sprint management, story point planning, and reporting procedures.

Finishing a Sprint Plan

1. If you put any time into your ongoing issues (Learn, Restructure, Peer Review), move them to Ready for Production. If not, leave them in Ready4Dev. Make sure story points reflect the actual time invested during this sprint.

2. Update story points of every In Review & higher issues to = actual story points invested this sprint. That includes issues at Done & Closed status.

• Don't change the story point value of Ready for Dev or In Dev issues
• If an issue is in Closed status & you ended up doing nothing on it, change story points & Effort size to 0. If the investigation/effort that led to deciding the issue should be closed, took time (more than 15-20 min, set to 0.1 or higher as appropriate).

1. Notify Jackie when done.

Sprint Planning

Pre-Planning

• Clean up your old branches in GitHub ("yours" = ones you are the main doc owner for, even if not listed in your name - always look at the "All" option):

  • Delete that were closed or merged and they're older than 1 week
  • Delete any that are open PRs or were never converted to PRs but will probably never be released (and/or would be too hard to merge with master by now).
  • If they're old and you don't plan to touch them in the near future, but there's a good reason to hold onto them permanently/long term, add a zz_ prefix to them. (Note that renaming will result in losing the old commit history, but the branch stays intact)
  • When done, all non-zz_ ones in your name should be things that you expect to work on in the coming sprint, or fairly soon after.

• Check your backlog. In particular:

  • Check if there are FeatureDoc items where the R&D work is done or in progress and add them to the relevant sprint.
  • Check if there are old stories/bugs that you probably will never do, because they're no longer relevant or their priority is so low, you'll never get to them. Delete these. If it ever becomes important, someone will create a new one.

• Check how many story points you should plan - based on upcoming vacations, company/country days off, special events that will use ½ day or more. In general, you should plan 0.6 story points for each full work day.

• Check which of your 'recurring' issues should stay in this sprint (i.e. team project, etc)

Planning Steps

1. Review issues already listed in the coming sprint & move everything you definitely don't expect to work on for the next 2 weeks into one of the following sprints, or back to backlog as makes sense.

2. Change Learn, Restructure, Peer Review issues back to Ready for Dev, and modify the story points back to 0.5, 0.5, 0.3 points respectively. (Yes, you have to move them back one status at a time as per our workflow.)

3. In the current (just ended) sprint, update story points of everything from In Dev through Ready for Production statuses to reflect the remaining effort. (And check that the story points for Ready4Dev stuff still looks accurate)

4. Move everything that's not Done/Closed from the current sprint to the top of the upcoming sprint.

5. Check if total story points in the upcoming sprint are >6. If yes, move lower priority stuff out to the following sprint.

   • Another option is to consider breaking large stories into 2 stories, and put the 2nd part into the following sprint if that's logical and will help.

6. Sort items in order of priority. You can use quick filters to separately sort priority on issues of different statuses. If you aren't sure how to prioritize, you can use this as a general guideline for ordering your issues:

   1. Anything that we've committed to publishing/making progress on in a particular sprint (incl blog posts, tutorials, etc)
   2. High value sprint goals
   3. Documenting new features that have already gone out or are going out this sprint
   4. Bug fixes & easy-to-implement doc feedback issues.
   5. Additional biggish content improvement, restructure tasks, doc-site improvements
   6. Little nice-to-have clarifications/tips that CS or another Cloudinary employee requested (or we created for ourselves) - content that isn't wrong, but additional information, better explanation, or better organization could be helpful.
      Note

      The above is just a starting point. Always use your best judgment to set specific priorities, but there should be a good reason for the order you select.

7. Notify Jackie when done.

Sprint Reports

Our sprint reports are located in this Google Sheet.

When each sprint is done, we generate a new report. Instructions for doing this are in this recording.

JIRA Management

Reporting Documentation Issues for Ourselves

Fill in the following fields. Items marked as critical are normally filled in by Product, but we can fill them in ourselves if we're reporting an issue to ourselves and don't need Product input on the priority.

Required Fields

• Summary, Description - Subject should make it clear that the issues are related to documentation and not just copy-paste of the dev issue title. Description should include all useful info for implementing the issue. If the issue can't be done now because of some dependency that isn't ready, prefix the summary with (OnHold - XXX) where XXX = short explanation of reason why it's on hold. For example: (OnHold - SDK) means we can't document it until the corresponding SDK issue is handled. (And the SDK issue should be listed in the Linked Issues section)

• Doc Type

  • Feature Docs - Any new docs reflecting dev work that impacts the end user (can be huge new features, minor product enhancements, changes to feature behavior, etc.). In almost all cases, these should be created via the JIRA automation & linked to the relevant dev issue.
  • Content Improvements - Bug fixes, added code examples, clarified information or other content updates that help the end user, but not related to any change by dev.
  • Restructure/UX - Splitting up content, converting text to tables, making information easier to read, or easier to search for.
  • Doc site - Changes to cld_docs or content_renderer that impact behavior or appearance
  • Blog, tutorial, demo - Self-explanatory
  • Strings and other tasks - Editing of UI/code strings, work on presentations, or any other internal task that doesn't result in an end-user deliverable (or anything else described above).
    
    Note

    If you just have to edit a few UI or doc strings for a feature you are documenting, no need to create a different JIRA for that of-course. It can fall under your FeatureDocs effort. But if you put significant effort (2+ hrs) into string edits - i.e. doc strings for an SDK or strings for multiple UI screens, please do create a separate JIRA for that with this DocType.

• Issue Type (story, bug, task)

  • Story - New or improved information
  • Bug - Correcting incorrect information
  • Task - Effort that doesn't result in an end-user deliverable

• Story Points - Estimated effort for current sprint. .6 story point = 1 day. Use 0.1 for under an hour. If a story was moved from one sprint to another when partially done (i.e. In Review), update the story points to indicate time remaining. Enables us to see how much time planned in our sprint, when looking at the Backlog view.

• Source: CS, Roadmap, Docs

  Note

  Docs as source means that we discovered the issue ourselves, not just that we reported it. For example, issues reported based on the System Updates are usually either Roadmap - if it was a feature that was planned in advance, or CS, if it was an issue that came up from a customer request

• Priority: Most are medium. High if important to finish in the current or max next sprint. Low if it's just a nice-to-have and customers won't miss it. For High priority issues, add to current or next sprint. Consider also adding Due date.

• Assignee: Set to Doc Team or to a specific Doc person

• Status: Ready for Dev (Gets set automatically if a doc team member assigns to Doc team or a Doc Team member)

• Epic Link - Select relevant Epic if exists. We should have Epics for any deliverables that are likely to take more than one sprint to complete. Epics should be broken into user stories, each of which can be finished within one sprint.

• Linked Issues: If the issue is to document a feature implemented by Dev or SDK, change the option to "caused by" and specify all relevant issues.

Reporting Documentation Blog Post Issues

In order to capture blog post stats for our dashboard, the following are required when creating/updating issues for Documentation Blog Posts:

• Component - Set to Blog. If a non-doc person will be the main author and you're just helping, use Blog-assist.

• Status

  • Evaluating - Idea for future blog post, not yet committed
  • Ready for Dev - Committed to writing, owner assigned, approximate publish date known
  • In Progress/In Review/Done - As usual

• Due date - Target/approximate publish date. Keep accurate to correct month and year.

Attaching an Existing Documentation Issue to the 'Causing' Development Issue

Sometimes you need to attach an existing Documentation issue to a Development issue. Follow these steps in EXACT order:

1. Make sure your Documentation issue is set as a "FeatureDoc" type
2. Go to the Dev issue you want to attach it to
3. If not already set, add "Doc" to the Additional Requirements field
4. Wait for automation to run (creates linkage)
5. Go to the automatically created doc issue and close it as duplicate
6. Link your original doc issue to the dev issue using "caused by"