Improving Documentation

[jromero]

I wanted to break up the suggestion from the Roadmap into its own topic so we can focus on what seems to be multiple facets of improvement.

The learning subteam has gotten some really good feedback about some shortcomings, and possible solutions for improvements. This discussion can be a general place to have further conversations which ultimately will generate actionable issues to implement.

References:

• Learning Sync: 2021-02-23

  📝 Meeting Notes

  • While learning about the concepts, in what order should they be taught?
  • Buildpacks vs builders can be confusing.
  • We hoped that builder image would be behind the scenes (not happening any time soon)
  • Leverage users existing knowledge of Dockerfiles?
  • App Journey is overly simplistic
    • Good for app developers
  • More “getting started” examples based on persona.
  • A general getting started guide that touches on all components in more depth may be helpful.
  • Components landing page can use a high-level diagram an explanation of interaction.
  • Build diagram helped understand the components.
  • Platform can be better explained or depicted in diagrams.
  • Birds eye view with a way to drill down.
  • How does a user know what they should care about/read about?
  • Overview where user can be prompt’d “if you care about this, go read…”
  • App Developer: needs an overview but don’t need to know everything
  • Buildpacks Authors: create buildpacks, they don’t care about stacks in-depth, they only care about what capabilities they have on a given stacks.
  • Infrastructure owners (operators): Need to provide stacks or recommend platforms.
  • Platform Implementor: Need to know about how lifecycle works. If they are using a builder they may lean only into creator or even use pack.
  • Builder author: only cares about stacks and buildpacks - they don’t care too much about lifecycle
  • Gradually introduce concepts based on which slice of the infrastructure is owned
  • Docs landing page can be a “presentation”-like overview
  • Each persona can have a getting started guide (overview)
  • Add it to roadmap
  • Blocking released on documentation
  • First-time users may need special attention (make it more obvious and easier to find)
  • It can be hard to determine where certain documentation belongs (a guide vs subject)
  • Break a subject page into topics
  • Add a tag/label to topic heading about skill-level (beginner, advanced)

[jromero]

Tutorial vs Reference

I would like to see more tasks specific tutorials similar to https://guides.rubyonrails.org/. I think https://buildpacks.io/docs/buildpack-author-guide/ is a good start, but there could be more.

-- @schneems comment

We have a tutorial for buildpack authors, but I think we need more reference-style material.

-- @ekcasey (comment)

[ekcasey]

I would suggest that reference docs should be comprehensive. I.E something should either be in:

1. the reference docs (everything)
2. both a tutorial and the reference docs (common workflows)

but never just in a tutorial.

[jromero]

Organization

Feedback

It can be hard to determine where certain documentation belongs (a guide vs subject)
-- @jkutner (meeting)

Current organization and nesting of pages is confusing. I have trouble predicting whether the information I am looking for is in tools or concepts or a guide. Examples (non-comprehensive):

• Some of the top level content feels very pack specific so I have trouble understanding why some content goes in tools/pack vs. the App Developer's Guide
• Why is guidance on how to crate a stack in concepts/stacks instead of a Stack Authors Guide?

-- @ekcasey (comment)

[natalieparellano]

I found this article to be thought provoking WRT the way we organize our documentation: https://www.worldofbs.com/why-documentation-sucks/

[jromero]

Platform Authors

Missing guide for platform authors

-- @ekcasey (comment)

[jromero]

Backfill

We add docs as we add features (much better than what we used to do), but could afford to back up and fill in older missing information. For example we have a section on cache images but never describe the (default) volume cache workflow (unless it in there and I just haven't found it yet).

-- @ekcasey (comment)

[jromero]

Persona-specific Getting Started

In addition to a general Getting Started tutorial, add persona-specific Getting Started tutorials.

• Platform Implementor: Need to know about how lifecycle works. If they are using a builder they may lean only into creator or even use pack.
• Builder author: only cares about stacks and buildpacks - they don’t care too much about lifecycle
• Gradually introduce concepts based on which slice of the infrastructure is owned
• Each persona can have a getting started guide (overview)

-- @samj1912 (meeting)

[jromero]

Diagrams to Represent Interactions

• Components landing page can use a high-level diagram an explanation of interaction.
• Build diagram helped understand the components.

-- @samj1912 (meeting)

[jromero]

General Getting Started

• Docs landing page can be a “presentation”-like overview
• A general getting started guide that touches on all components in more depth may be helpful.
• Leverage users existing knowledge of Dockerfiles?
• Birds eye view with a way to drill down.
• How does a user know what they should care about/read about?
• Overview where user can be prompt’d “if you care about this, go read…”

-- @samj1912, @yaelharel, @jkutner (meeting)

[jromero]

Skill-level Topic Annotations

• First-time users may need special attention (make it more obvious and easier to find)
• Break a subject page into topics
• Add a tag/label to topic heading about skill-level (beginner, advanced)

-- @danielleadams (meeting)

[dfreilich]

“I think we need tiered user docs. We talk about the progressive complexity of the spec, but at every entrypoint into CNBs we give users the full complexity of the specification. We should actively be hiding certain parts of the spec from the docs, and putting it behind a "learn more" gate in order to make it more approachable.”
from @nebhale, quoted by @sampeinado here - #62 (reply in thread)