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 (and other recurring) issues back to Ready for Dev, and modify the story points back to 0.5, 0.5, 0.3 points respectively. If a DOC issue is in Ready for Production status, you can move it directly back to Ready for Dev status.

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 This field helps with reporting the types of things we work on. I often use this field when generating quarterly reports and when preparing for midyear or annual reviews. Please do your best to set these values correctly per these descriptions.

  • Feature Docs - Use for new doc content reflecting R&D 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 automatically created via the "Additional Requirements = Documentation" JIRA automation & auto-linked to the relevant R&D issue. But set this value manually if you document a new/modified feature (or an old one that was just never documented before) and it doesn't have a corresponding R&D issue to auto-generate from.
    Note

    If changing the DocType field value of an existing doc issue to this value, please also change the actual JIRA type from a story/task to the FeatureDoc type. JIRA will then request that you migrate the issue to the FeatureDoc workflow - just click Next until done.
  • Content Improvements - Use for bug fixes, clarified information or other content updates to existing content that help the end user, but not related to any update to the feature itself.
  • Doc site - New/updated frontend or backend functionality for the doc site, build/GitActions OR new/improved UI elements for the doc homepage or main page layout.

    In general, things that impact the overall look, performance, or behavior of the doc site for end users or the build process for the authors.

  • DevX/UX: Use this when the main goal of the task is to create or modify content (in doc site, blog posts, cloudinary-devs repo) for to improve human developer/customer experience.  Examples:
    • converting long texts to a table
    • restructuring a page or section for better skimmability
    • adding/improving visual content like diagrams, video tutorials, showing a comparison of original vs transformed assets using a particular feature
    • adding new code examples, demo apps, or use-cases to help developers understand when/how to implement the feature
    • VSCode Extension or other new developer tooling products/features
  • Blog, tutorial, demo - Developer content where the main target is to publish outside the doc site (even if also published or linked to from the doc site)
  • 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.
  • Data analysis - Implementation of new GA4 events, reporting data results, work with data team to determine new queries/plan experiments, efforts related to data dashboards, etc.
  • AI productivity - Implementation of internal skills, commands, rules, shared GPTs, or other AI-specific efforts or research aimed at making your work or that of other employees more efficient.
  • Agentic experience - Use when the main goal of the task is better agentic consumption/discovery (even if it might also help human developers)
  • Self service - Use for tasks specifically related to the Cloudinary Self-service OKRs and unrelated to the doc site.

• 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"