Presenters
Source
Unlocking Developer Potential: Neo4j’s Revolutionary “Lego Bricks” and “Golden Paths” for Documentation 🚀
Ever felt lost in a sea of technical documentation, desperately searching for that one crucial piece of information? You’re not alone! Traditional, monolithic documentation can be a real headache for developers, leading to frustration and wasted time. But what if there was a better way? At Neo4j, they’ve been on a mission to transform the developer documentation experience, and their innovative approach using “Golden Paths” and “Lego Bricks” is a game-changer. ✨
This session dives deep into how Neo4j is revolutionizing how engineers create software by making documentation not just accessible, but exciting and actionable. Get ready to discover a more modular, opinionated, and user-centric way to build and consume technical guidance.
The Monolithic Documentation Maze: A Developer’s Nightmare 😩
Remember those sprawling, lengthy learning paths that felt like climbing Mount Everest just to find a single answer? Neo4j did too. Their previous “learning path” was comprehensive, but overwhelming. For developers needing a specific piece of information, wading through pages of content was inefficient and time-consuming.
The challenges were clear:
- Navigation Nightmare: It was tough for engineers to find what they actually needed, especially when they only required a small subset of information.
- Maintenance Mayhem: Keeping such a massive body of knowledge up-to-date, especially when functionality was distributed across multiple teams, became an unsustainable burden for a single team.
Embracing the “Golden Path”: Bite-Sized Guidance for Success 🎯
Inspired by Spotify’s “Golden Path” concept – an opinionated yet well-defined and documented way for engineers to build software – Neo4j recognized the need for a more digestible approach. The goal? Documentation that is organized, meaningful, and easy to navigate.
They adopted a brilliant “shop” metaphor for their platform, offering readily consumable tools and guidance. But how do you know what developers truly need? Neo4j is all about data-driven improvement:
- Backstage Insights Plugin: This powerful tool helps identify the most popular documentation, guiding where to focus efforts.
- DX Survey Tool: Short, targeted surveys sent directly to developers on Slack gather real-time feedback, ensuring improvements address actual pain points.
Introducing “Lego Bricks”: Composable, Opinionated Documentation 🧱
The real magic happens with their “Lego bricks.” Imagine self-contained, highly opinionated, and detailed documents that focus on a single, specific task an engineer might undertake. Think of it like a single, perfect Lego brick for building a specific part of your software.
Each “Lego brick” provides everything you need for that task:
- Prerequisites: What you need before you start (e.g., an existing service in Go).
- Features: The awesome benefits you’ll gain.
- Setup Instructions: Clear, step-by-step guidance.
- Off-Path Guidance: What to do if you need to deviate and the potential consequences.
This composable nature means engineers can snap these bricks together to build more complex solutions. And here’s the kicker: other teams can create and contribute their own bricks, fostering a product engineering mindset across the organization! 👨💻
The Dietaxis Framework: Purpose-Driven Documentation 🗺️
To further refine their documentation strategy, Neo4j embraced the Dietaxis framework. This clever framework categorizes documents along two crucial axes:
- Activity vs. Thinking: Docs that guide action versus those that foster understanding.
- Acquisition vs. Application: Docs for learning new skills versus those for applying existing ones.
This framework ensures each document has a clear purpose and encourages splitting multifaceted guides into more focused, purpose-specific ones.
New Documentation Types for Every Need 🛠️
Building on the “Lego brick” concept and the Dietaxis framework, Neo4j has defined several distinct documentation types:
- Lego Bricks: For specific, actionable tasks.
- Architectural Decision Records (ADRs): The “why” behind technical choices. Think of it as explaining why you chose an induction stove over a gas one! 💡
- Playbooks: Your go-to troubleshooting guides for when things go wrong, like a cooktop’s troubleshooting manual.
- Migrations: Step-by-step guides for transitioning between systems (e.g., Datadog to Grafana). ✈️
- Tutorials: Opinionated guides that teach engineers how to achieve specific goals, often by leveraging existing “Lego bricks.”
Enhancing the Reader Journey in Backstage 🌐
Neo4j has seamlessly integrated these documentation types into Backstage, creating a truly intuitive reader experience:
- New Docs Homepage: Easily filter by document type and quickly access your favorite or recently read docs.
- Improved Tech Docs Reader: Features like “resume where you left off,” essential metadata (owning team, update date, estimated read time), and links to relevant further reading and Q&A make for a smoother experience.
- Dedicated Entities for ADRs and Playbooks: While the content might live
within parent component docs, dedicated entities make them easily
discoverable. They cleverly use
tech-entityandtech-entity-pathannotations to link to the content without any duplication.
Empowering Writers and Looking Ahead 🚀
The platform also makes life easier for writers! A helpful modal guides users to select the appropriate document type, and the Backstage Scaffolder automates the creation of Pull Requests for new documents, streamlining the contribution process.
Future plans include:
- More reference-focused document types.
- Exploring “composite docs” that dynamically combine multiple documents for specific use cases (e.g., a guide for creating a production-ready API service using a set of Lego bricks).
Addressing Backstage Limitations and Open Sourcing 💡
Neo4j is also transparent about some Backstage limitations and their commitment to improvement:
- No built-in “Document” kind: This hinders richer relationships between docs and software components and limits metadata storage within the catalog.
- Desire for native composite doc functionality: A built-in mechanism would significantly enhance this capability.
- Fiddly hiding of documentation entities: Filtering assumptions in the catalog make selective hiding challenging.
They’re dedicated to open-sourcing their improvements, including functionality for tracking recently read documents and sharing their document templates with the community.
Key Takeaways for Better Documentation 🔑
For platform engineers and anyone looking to elevate their documentation game, Neo4j offers these golden nuggets of advice:
- Understand your business needs: Figure out which documentation types truly make sense for your organization.
- Steal and adapt: Don’t reinvent the wheel! Leverage Neo4j’s proven structures.
- Seek buy-in: Involve your users. Don’t impose a system; build consensus!
- Leverage Backstage’s flexibility: Build custom experiences that truly serve your readers and writers.
The session concluded with a powerful quote from Albert Einstein: “If you want good docs, don’t just tell people to write docs. Create a docs experience that encourages contribution.” This perfectly encapsulates Neo4j’s philosophy: making documentation creation a rewarding activity, not a chore.
Q&A: Navigating the Documentation Tool Landscape 📡
When asked about competing with other documentation tools, Neo4j clarified their inclusive strategy. While they champion “docs as code” within their Aura engineering organization, they understand the continued value of tools like Confluence for quick, ad-hoc changes. Their approach is to support both. They plan to integrate Confluence content into their search and provide seamless linking from component entities to Confluence documentation. The key takeaway? They will never dictate where engineers must place their documentation, recognizing the valid reasons for diverse approaches.
Neo4j’s “Golden Paths” and “Lego Bricks” are more than just a documentation strategy; they’re a blueprint for empowering developers, fostering collaboration, and building better software, faster. 🚀