Skip to content

Spotify Technical Documentation

Presented by Gary Niemen, Product Manager @ Spotify

The Hero's Journey

Solving Spotify's technical documentation at scale

heros-journey

Ordinary World

Referes to internal technical documentation (to assist amongst internal teams and engineers).

  1. Spotify has a culture of self-managing teams how they want e.g. for the technical documentation every team member was writing documentation everywhere. It was scattered so other engineers had a hard time to find these documentations.

  2. Not Finding the Information that you need was a 3rd company blocker amnogst engineers.

  3. Their solution was inspired by a problem at Google.

Crossing The Threshold

  1. Were able to create it in two weeks with support of other internal Spotify staff.

  2. Had a CI/CD system.

  3. Used mkDocs as the static site generator (stable and tested).

  4. Storage on Google Cloud Storage.

  5. Exposed the websites using their internal developer platform.

Hero's Journey Problems

  1. Discoverability & Findability (search)

  2. Trust (how can you trust what you find)

  3. Maintenance

  4. Feedback Loop (making comments to correct the docs incase of problems)

  5. Hidden Knowledge (many engineers having unshared knowledge)

  6. Ownership (no handover process to eventually ensure ownership)

  7. Used and useful (Need to know that it is used and useful)

  8. Adoption and Engagement (different needs cannot be ignored)

The key problem underneath is getting unstuck.

Creating a trust card (measuring using a percentage how reliable the documentation is)

Implementation of code-like graphics

The Reward
  1. Impact created in the company with well maintained technical documentation (positive feedback)
Success Factors

  1. Cross-functional team (different team skillset)

  2. Fully embraced docs like code

  3. Quick development of a minimum lovable product

  4. Good adpotions

  5. Collaborations

  6. Clear and inspiring vision

The Ressurection
  1. Convincing other technical writers that docs like code is the way to go.
Takeaways

  1. Keep focused on the key problem.

  2. Keep the solution simple.

  3. Fiercely optimise for the engineer.

  4. Enable others to build on the platform.

  5. Standardize and centralize.

References

Comments