Skip to content

Proposed General Structure for Playbook Chapters The below template (markdown) proposes a general page structure to be used as a guideline for all pages that should be published under the Data Products Playbook.

Chapter Title#

A short title describing the content that will be taught in this chapter.

Overview#

Brief 2-3 sentence description of what this chapter covers and its importance in the data product lifecycle.

What you will learn#

Describe what will the reader understand after reading this chapter, key skills they will gain, how this chapter will help them create a data product.

Key Personas & Stakeholders - RACI Matrix (optional for development guides)#

Create a RACI Matrix (Responsible, Accountable, Consulted, Informed) if there are multiple personas involved in activities for the chapter. The structure should indicate the persona involved, their level of responsibility and the activities or actions that they will be driving or involved in.

See below example:

Activity Data Product Manager Data Engineer Data Analyst Business Stakeholder Governance Team
[Key Activity 1] R/A C I C I
[Key Activity 2] A R C I C
[Key Activity 3] C R A I R

R = Responsible, A = Accountable, C = Consulted, I = Informed

Prerequisites#

  • Required knowledge or completed previous chapters
  • Necessary tools, access, or resources
  • Stakeholder alignment needed before proceeding

Step-by-Step Process#

Step 1: [Action Name]#

  • Detailed instructions
  • Expected outcomes
  • Common pitfalls to avoid
  • Downloadable templates

Step 2: [Action Name]#

  • Implementation details
  • Quality checkpoints
  • Success criteria

(Optional) Success Metrics & Checkpoints#

If this is a heavy technical chapter, describe how do we measure that we are done with the work described in the chapter.

  • Checkpoint 1: [Specific validation criteria]
  • Checkpoint 2: [Measurable success metric]
  • Checkpoint 3: [Stakeholder approval requirement]

(Optional) Common Challenges & Solutions#

  • Challenge: [Typical problem encountered]
  • Solution: [Recommended approach]
  • Prevention: [How to avoid this issue]

Next Steps#

  • What to do after completing this chapter
  • How this connects to the following chapter
  • Immediate action items

(Optional) Additional Resources#

  • Links to relevant documentation
  • Further reading recommendations
  • Community resources or support channels

General guidelines for writing the Playbook#

  1. Navigation Elements Always include breadcrumb navigation at the top Add Previous/Next links at the bottom for sequential content Use consistent link formatting: Text

  2. Info Boxes Use the below info boxes for communicating specific bits of information outside the flow of the text.

    !!! info for general information

    !!! tip for helpful suggestions

    !!! warning for important cautions

    !!! success for key takeaways

    !!! example for code examples

  3. Code Blocks

  • Use collapsible sections for large code examples

  • Always specify code language for syntax highlighting

  • Include comments for clarity

  1. Consistent Sections
  • Prerequisites before main content
  • Learning objectives when applicable
  • References/links at the end
  • Troubleshooting for implementation guides -> Reach out to our team
  1. Other important note
  • Address the reader directly (“You…”) and stay consistent with terminology so AI search or global search returns relevant results. Prefer bullet lists and tables for dense info; reserve paragraphs for conceptual explanations. Review with someone from the target audience to spot gaps before publishing.