Documentation & Onboarding Materials

[abbey]

Hey all!

Wanted to share a writeup that captures a great session held last week on Discord between a couple folks regarding our strategy with documentation & onboarding materials.

@Kaidao @joelhans @efstajas @brandonhaslegs @andrewd and I sat down to talk about our next steps with docs.radicle.xyz — the project-wide “docs” site that up until now, has been out-of-date and failing to capture what Radicle actually is.

Over the last month, @joelhans has done a great job of cleaning up the site and getting them at least up to date with our product work (see closed PRs for his work done).

our new and improved docs site!

Looking Forward

Now that we have things in an adequate state, we can start looking forward and tackling some of the larger questions we have regarding the future of docs.radicle.xyz and our documentation strategy in general. This is what we started discussing in our chat last week.

To structure our session, I wrote up a couple guiding questions. We worked together to try to answer some of them:

• What do we think is the difference between documentation & onboarding materials?

  • Generally, we can classify our two types of documentation as end-user/user-facing and developer/protocol. We can further classify user documentation into two types:
    1. Product-specific (how to use a product/feature, how to troubleshoot, tutorials/guides)
    2. General (user onboarding, value prop, marketing)

• What would we say are our biggest problems when it comes to documentation & onboarding materials?

  • End-user/user-facing:
    • Maintenance — User-facing documentation goes out of date fast, especially when they include rich text like images & videos. Also, nobody is explicitly responsible for maintaining the docs, which keeps it from being top of mind.
    • Fragmentation — Because there are different solutions/products for the same user problems, there is a confusing user experience. We need something more unified to ensure a user can do X, without navigating to five different sites
  • Developer/protocol:
    • Accessibility — Since Core Teams organize independently, they all use different tools for documentation. Docs are scattered between READMEs, HackMDs, and websites. We might benefit from having a better way to find out who’s docs are where.

• What documentation do we have now?

  • docs.radicle.xyz - General value prop (What is Radicle), Getting Started (user onboarding) Upstream & CLI user-facing product documentation, FAQ/Troubleshooting, Community docs, light Link development documentation (protocol overview in How it Works)

  • radicle.network - CLI user-facing documentation

  • drips.network - Marketing website & general value prop for Radicle Drips

  • docs.drips.network - User-facing Drips documentation

  • radicle-client-services - seed node / services developer documentation?

  • radicle.xyz - Marketing website, general value prop descriptions, link throughs to doc & communication hubs

  • radicle.mirror.xyz - Blog posts, onboarding guides (example)

  • Other developer docs hidden in different repositories (e.g. radicle-link/docs)

• How do we see documentation being maintained between Core Teams?

  • We believe developer docs should be maintained by individual Core Teams. This ensures the easiest & most effective maintenance. We do, however, see a need to unify user-facing documentation when it is related to a Radicle experience that currently uses different tools across the stack (and across Core Teams).

Takeaways

In an attempt to structure this conversation into intentional next steps, I’ve tried to boil down our discussion to a set of takeaways that we can discuss further. Please note that these are just the shared opinions of those who were on the call, we’re sharing here to make sure that we can involve more stakeholders in the discussion and develop our next steps together. Here’s what we came up with:

• We don’t need a central hub for all of our docs, we need unified user documentation for our code collaboration product offering. This is the user experience that touches the most Core Teams and is suffering from the most fragmentation & maintenance issues. Other recommendations/thoughts that surfaced:

  • Upstream & Alt-Clients need to work together and decide:

    1. What code collaboration experience we want to optimize adoption of
    2. What additional user-facing documentation @Growth and @Product contributors think we need to best support that onboarding/adoption
    3. Who maintains what user-facing documentation and how do our user-facing “domains” work together (docs.radicle.xyz & radicle.network)

  • Drips user-facing documentation (e.g. docs.radicle.network) should stay separate! It can be introduced to docs.radicle.xyz when it starts integrating more into the code collaboration stack.

  • We need to work on an updated overview of Radicle’s code collaboration value prop. We should be sure to tie into the work @thom is doing on Branding/Messaging, but maybe should focus on creating a better technical “one-pager” on what Radicle is and why it’s important — similar to our beloved Stefan Hajnoczi: Understanding Peer-to-Peer Git Forges with Radicle article. This can be a refresh of “What is Radicle”.

  • If we believe that developer/protocol documentation should live within Core Teams, then we should probably remove any Radicle Link documentation from the docs.radicle.xyz hub and instead link through to @Link team’s docs in radicle-link/docs.

  • We need a process for maintaining documentation that is cross-team (e.g. Upstream & Alt-Clients). Developer documentation should remain in the hands of individual Core Teams, but we need a better process and mutual responsibility for maintaining our collaborative user documentation.

    • Specifically, we need to work on our FAQ/Troubleshooting resources for the pieces of the stack that touch our documented code collaboration experience AND develop a process for taking technical explanations from Core Teams and documenting it.

  • We need to define a clear user onboarding experience from the get-go. @brandonhaslegs @Julien @efstajas should decide how much of this should be hosted on radicle.xyz and how much should be on docs.radicle.xyz. This will inform where we go next with @joelhans work.

  • We believe docs.radicle.xyz should also be the future home for our Contributor and Governance documentation. We can expand our docs in a organized manner, by organizing types of documentation with Subpages (see picture below). We could even host developer documentation here (e.g. Radicle Link), just delegate maintenance of specific parts of the radicle-doc repository to their respecitve Core Teams.

Action Items & Next Steps

• For @Kaidao @joelhans @efstajas @brandonhaslegs @andrewd, please add anything that you think I missed from our session.

• We’d like to set some clear deliverables for the next version of docs.radicle.xyz, so are currently sourcing opinions & thoughts on is still missing from our code collaboration user-facing documentation. What is currently missing from our user-facing documentation to best enable users to use Radicle as a code collaboration tool? @nas @Kaidao @efstajas @Julien

• A responsibility discussion regarding ownership of user-facing documentation between Upstream and Alt-Clients cc @Kaidao @efstajas @cloudhead

• A structural discussion about how we can utilize Subpages to better organize docs.radicle.xyz @joelhans @abbey @Kaidao maybe?

• A personnel discussion — do we need to bring someone on to the team to help maintain our collaborative documentation (e.g. work with Core Teams to turn issues into FAQ/Troubleshooting docs, or write & publish release announcements?)

I hope that this is enough to get the ball rolling on next steps. The whole “docs” discussion touches a lot, but if we can start boiling it down to specific issues, we can start making progress!

Thanks for reading

[bordumb]

We need a process for maintaining documentation that is cross-team (e.g. Upstream & Alt-Clients). Developer documentation should remain in the hands of individual Core Teams, but we need a better process and mutual responsibility for maintaining our collaborative user documentation.

Specifically for Developer Documentation:

I think finding a way to (somewhat) automate documentation would go a long way here. I’ve seen a lot of success when adopting a Docs As Code practice.

This includes things like (copied from site above):

• Having technical writers integrated with development teams
• Developers always writing the first drafts of documentations for new features
• Putting hard blocks on merging of new features if they don’t include documentation, which incentivizes developers to write about features while they are fresh

To address some possible open questions on any of these:

How do we get started with technical writers if our team doesn’t have one?

We can start with baby steps. Such as writing an RFP and getting the work funded through a grant to test out several different technical writers.

How can we deal with the added overhead of (developer) documentation?

There are doc automation tools that (somewhat) automate doc creation (e.g. Sphinx Docs). Sphinx is typically used to create docstrings that are nested directly into source code (this needs to be manually written by developers), then parsed and turned into HTML pages automatically. This would help cover - I’m guessing - 60-70% of documentation needs. We’d still need to do manual work when it involves embedded images, diagrams, and such. Definitely better than relying on completely manual processes and ending up with much less doc coverage.

We need to define a clear user onboarding experience from the get-go.

I think the design-centered approach of coming up with personas might help here.

For example, the persona of a “Developer DAO” who wants to do the following with Radicle:

• Self-host seed node / code base
• Collaborate across multiple teams / products

You’d probably need several articles that go over

• Setting up a node (also maintaining / enhancing the node?)
• All the basics for collaborating (push, pull, commit, Radicle CLI, etc.)
• Advanced topics on collaborating (connecting to peers, using Upstream, etc.)
• Paying contributors (Setting up Drips)
• Building revenue (Setting up a Community/Subscription)
• How to setup documentation pages using Radicle (to facilitate async work as much as possible)

And possibly more articles.

[Kaidao]

Thanks @abbey for writing this up! I think this is a great overview of our conversation and next steps to get the work going. I agree with all of your points, especially around the current problems we face and what we need to solve for.

@bordumb 's suggestion makes a lot of sense to me. We should start with defining the various user personas that we believe will be perusing our documentation, list them out, and then we can determine what documentation should be general and what documentation should be product-specific. From there, we’ll also be able to easily determine any gaps with our current documentation. To kick things off, I propose we set up a shared doc (Notion?) and assign a few core team members to be responsible for coming up with that initial list.

One thing I’d like to point out, though, is that whatever solution(s) we decide to implement for maintainability should be optimized for speed, IMO. Especially at this stage of our product, where we’re still pivoting and trying to achieve product/market fit, the changes will come very fast, and we need to have a structure that allows us to be as nimble as possible.

[joelhans]

@abbey: Thanks so much for the fantastic breakdown of the current docs landscape and our conversation.

Some scattered thoughts on the various points so far.

---

We don’t need a central hub for all of our docs, we need unified user documentation for our code collaboration product offering.

I still think Radicle should think of a central hub for all docs as a long-term goal, but recognize that’s too big of an ask, in terms of resources and time, to achieve right now.

The narrow focus on a “unified user documentation for code collaboration” is the right angle for now, but it also implies that there’s a single “Radicle approved” method of code collaboration using CLI, Upstream, and the web client. I’m not sure if the core teams would agree with that idea.

For example, one can review a patch in a few ways:

1. Via Upstream: track a remote user in the app, view a patch, then use upstream and git checkout to view changes locally
2. Via the CLI: track a remote user with rad track, then use git diff to compare the tracking branch against your local branch
3. Via the web client: select a contributor’s branch using the tree selector, view the diff of a commit (example), and then follow either 1 or 2 to complete the task.

There has to be a decision whether to present all the options for performing an action or achieving a goal, or provide a single opinionated path using the “best” tool for the job.

Both solutions aren’t perfect and come with a handful of UI/UX/copy challenges. Nothing insurmountable, but important enough to discuss early and plan ahead.

There has been a bit of discussion around this in a closed PR on adding Upstream docs on a UX level as well.

---

• Having technical writers integrated with development teams
• Developers always writing the first drafts of documentations for new features
• Putting hard blocks on merging of new features if they don’t include documentation, which incentivizes developers to write about features while they are fresh

First off, fully agree with @bordumb on these points around process. It would be great to define docs requirements across Radicle’s core teams, while letting each group of developers self-organize around how they want to produce, organize, and collaborate on their documentation.

But I would still advocate for pushing, eventually, toward a single developer docs hub, just like Radicle might have for user docs—they might even be in the same place.

I think it would be a really cool and valuable experience, eventually, to allow developers to quickly hop between CLI and Drips docs, for example, if they’re building an app that bridges the two protocols.

Technically it’s possible to have each core team do their developer documentation independently and then merge all their work together into one developer docs hub. GitHub Actions could fetch developer docs from any number of repositories, convert them into Docusaurus-compatible Markdown using pandoc, and publish everything in parallel. Docusaurus then becomes a scaffolding tool, helping organize developer docs into a nice HTML experience.

Radicle developers focus on writing/updating docs, not worrying about how they’re presented, using their ideal workflows, and external developers get the nice UI/UX that Docusaurus provides.

---

We need to work on an updated overview of Radicle’s code collaboration value prop. We should be sure to tie into the work @thom is doing on Branding/Messaging, but maybe should focus on creating a better technical “one-pager” on what Radicle is and why it’s important — similar to our beloved Stefan Hajnoczi: Understanding Peer-to-Peer Git Forges with Radicle article. This can be a refresh of “What is Radicle”.

This is something I currently have in-progress. I didn’t very much available time in May, but it’s something that I’d like to return to in the immediate future. It’s probably a bit more content than you’d typically find in a “one-pager,” but once we have a full version, we can always simplify and publish both for different readers (simple vs. the full picture).

Here’s a relevant GitHub issue, which I should probably update.