Developer Relations & Advocacy is often described as the work of helping developers understand and use a product.
That description is correct, but there is more. In this blog, we will share what we learned while turning a community Developer Relations guide into a structured documentation site with Thally.
A Developer Advocate might write a technical tutorial, deliver a conference talk, review an onboarding journey, support a community, build a sample application, or take recurring developer feedback back to a product team. The work connects people, products, education, and experience.
This range is part of what makes Developer Relations exciting. It is also what makes the field difficult to learn.
Useful knowledge exists across conference talks, community conversations, personal blogs, company playbooks, videos, and the experience of practitioners. Someone entering the field can find definitions easily, but finding a dependable path from understanding DevRel to doing the work is much harder.
Those are some of the problems the DX Guide provides solutions for.
Why we built the DX Guide
The DX Guide is a community-built knowledge base for people learning, practising, or leading Developer Relations.
We wanted to create a resource that did more than define common terms. It needed to help readers understand the work, apply practical frameworks, learn from real community examples, and find useful next steps.
The DX Guide started in 2025 as a project within the DXMentorship cohort. We built its first version with Mintlify, and members of the DX community in that cohort contributed their knowledge and experience to the guide. That beginning shaped the project as a community resource. It was never meant to represent one person's view of Developer Relations.
The first version gave us a valuable foundation. As the material grew, we also saw opportunities to improve how readers moved through it, how contributor work was credited, and how the documentation could be reviewed and maintained. That brought us to the next stage of the guide and, eventually, to Thally.
The guide covers areas such as:
- Developer Advocacy
- Developer Experience
- technical content and documentation
- public speaking
- community building
- feedback collection
- measurement and reporting
- careers and professional development
- real examples and lessons from practitioners
The aim is not to establish one permanent definition of DevRel. The field changes, and different organisations structure the work differently. The guide gives the community a shared place to document what people are learning and improve it through review and contribution.
Why we moved the documentation to Thally
The original documentation contained useful material, but having content is not the same as having a dependable documentation experience.
Some pages repeated their introductions. Navigation needed a clearer structure. Contributor examples needed context and attribution. Product references needed official links and recognisable identities. The site also needed a consistent visual system and a workflow the team could continue to maintain.
The SYNCHACK challenge gave us a practical reason to address those issues through Track 2, which focuses on launching or migrating a documentation project.
We chose Thally because we needed more than a place to display Markdown files.
We wanted a publishing foundation that could support structured navigation, reusable content, search, deployment, and agent-facing ways to discover the same source material.
Our project now contains MDX pages organised into topic-based navigation groups. It includes practical guidance, contributor stories, event photographs, professional links, product resources, and a changelog.
The Books page is one example of the broader goal. It is not an isolated list added to increase the number of pages. It gives readers a route from the guide into deeper learning.
Migration was only the beginning
At first, documentation migration can look like a file-moving task.
Move the Markdown.
Recreate the navigation.
Add the logo.
Deploy the site.
In practice, the more important work was editorial.
We reviewed the guide page by page. We removed repeated introductions and duplicated sections. We replaced emoji headings with a consistent icon system. We revised indirect language so organisations and contributors were described clearly. We checked links, image context, headings, descriptions, and related-page paths.
We also tried to make every example earn its place.
A photograph is not useful simply because it looks good. It becomes useful when the surrounding text explains what a reader can learn from it without inventing details that were never verified.
Joy Ndukwe's DevFest photograph supports the guide's discussion of public speaking and community work. We use the information we can verify and avoid assigning an unconfirmed session title or outcome to the image.
The same principle applies to project and community examples. In the photo above, Ekemini Samuel is presenting a talk at Mojo Africa Community event.
Real work makes the guide more concrete, but accurate context matters more than promotional language.
Designing a technical knowledge base
We wanted the DX Guide to feel technical without feeling cold.
We selected JetBrains Mono as the primary typeface. It gives prose, headings, commands, and examples a consistent voice that feels familiar to developers. We paired it with a restrained colour system built around deep green, lime, and violet.
The DX mark gives the guide a recognisable identity, while the interface keeps the documentation itself in focus.
The image below shows the LinkedIn and Personal Branding chapter in the DX Guide
The technical challenge we did not expect
The production deployment did not work perfectly on the first attempt.
A build failed because the synchronized application expected runtime modules that were missing from the repository snapshot. The error appeared across documentation, search, API, and well-known routes.
Thally provides clear insights into the documentation deployment pipeline
The solution was not to copy a quick runtime fix into the documentation project. Thally's runtime and the authored documentation have different ownership. The repository received a runtime synchronization, and the related static-route tests were aligned with that version.
After the update, the project checks, tests, and production build passed.
This was one of our most useful lessons. Documentation teams need to understand where content responsibility ends and platform responsibility begins. A workaround in the wrong repository can solve today's build while creating a harder maintenance problem tomorrow.
What Thally helped us do
Thally gave the guide a structured route from authored content to published documentation.
It helped us bring together:
- MDX content
- organised navigation
- reusable page components
- search and publishing surfaces
- deployment checks
- agent-facing documentation surfaces
It also gave us a practical environment for reviewing the documentation as a product rather than treating it as a folder of files.
With the analytics, we have insights into the DX documentation, knowing what to improve as we grow
The workflow worked best when automation moved the work forward and people remained responsible for what was published.
What we learned
The biggest lesson was simple: documentation migration is also editorial work.
A successful build does not automatically produce clear documentation. A large page count does not guarantee useful coverage. Search cannot repair an unclear information structure. A polished design cannot replace evidence and attribution.
We learned to ask better questions:
- What is the reader trying to accomplish?
- Does this page provide a useful next action?
- Is this example supported by evidence?
- Have we distinguished verified facts from assumptions?
- Can another contributor understand and maintain this structure?
- Does the downloaded or deployed result behave like the preview?
We also learned that a living guide needs visible maintenance. The changelog, contribution guide, repository history, and review process are part of the documentation experience.
Here is our Changelog in the DX documentation
Building with AI assistance
We used AI assistance during parts of the research process. Google, ChatGPT and Claude helped us inspect patterns, investigate errors, and support validation workflows as we worked through the documentation.
We also used the Thally documentation to research the platform, confirm technical details, and understand the workflow required for the migration.
What comes next
The DX Guide is a living documentation.
We want to continue improving the practical paths through the content, expanding contributor examples with permission, checking the guide's agent-facing surfaces, and making it easier for new community authors to participate.
We would love to see people use the guide to understand a DevRel problem, complete meaningful work, and contribute a lesson that helps the next person.
Explore the guide: advorel.thally.app
What would make a community Developer Relations guide more useful in your day-to-day work? Please share in the comment!
A big thank you to the SyncHack and Thally team! 🎉
And thanks to Joy, Samuel, Adedotun and Ekemini for working together as we did the migration of the DX documentation to Thally.
Thank you for reading! 💜
Top comments (0)