Tutorials and Examples System

Hi, all!

Through August-ish, the TDB team is focused on the primitives that make up Web5 - that’s the SSI Service and SDK, and our DWN Implementation. The best way to contribute code there for newbies is through the issues tagged as “good first issues” or “help wanted”[0][1][2].

As the projects get closer to feature-complete, we want to help folks know how to use their APIs. So we’re creating a system to house tutorials and examples. It’s got the following goals:

  • Make it easy to contribute examples and tutorials, following a common template
  • Provide docs alongside the code
  • All code remains tested throughout the project lifecycle
  • Everything in the system gets published on developer.tbd.website
  • …with credit to the author(s)!

A really great example of a tutorial was written and published by Frank Hinek[3]! We’d like to start, with his buy-in[4], by adapting this into a system that makes it super simple for folks to add more articles like this and keep 'em automatically tested and published.

So Angie and I are kicking off on this work, and we’d like it to be ready by the Fall when our projects will have much more to say about their APIs and how they can be used.

Would anyone like to dig in with us? Let’s make a plan!

  • Scaffolding out the tutorial/example repo
  • Making a template example for others to follow
  • Setting up build/test/publish hooks
  • Adapting Frank’s first examples
  • Other ideas??

Let’s gooo.

S,
ALR

[0] Contribute to TBD54566975/ssi-sdk · GitHub
[1] Issues · TBD54566975/ssi-service · GitHub
[2] Contribute to TBD54566975/dwn-sdk-js · GitHub
[3] Getting Started with TBD's SSI Service
[4] Discord

3 Likes

Count me in!

Given the open and collaborative approach TBD is taking with the Web5 project, great docs and onboarding guides will be crucial to driving engagement with the development community and potential commercial partners.

I particularly like the idea of incorporating automated testing to ensure the guides don’t get stale and cause frustration for those that come along months after initial publication.

This might be a lower priority / secondary consideration to getting the basic scaffolding and first few publications live, but a resource I’ve always appreciated when getting started with a new project is an easy to way to spin up a sandbox. This could be as simple as a set of Docker containers that people can self-host all the way up to a hosted code playground. We can start simple and iterate over time.

2 Likes

Blockquote
I particularly like the idea of incorporating automated testing to ensure the guides don’t get stale and cause frustration for those that come along months after initial publication.

:metal:t2:

Blockquote
a resource I’ve always appreciated when getting started with a new project is an easy to way to spin up a sandbox. This could be as simple as a set of Docker containers that people can self-host all the way up to a hosted code playground. We can start simple and iterate over time.

This is great. Let’s track this as a feature we can unlock for runnable services in the new repo’s issue tracker.

Building on that, I was also thinking about leveraging an examples/tutorials system as a base to write new code. For instance, say the user knows they want to issue a credential. What can we do to generate the scaffolding for a new project in their language/build system of choice to jumpstart that codebase for them? Like an npx create-react-app or a start.spring.io or code.quarkus.io.

But as you say: “iterate over time”.

Anything else to consider in this system before we make a new repo and start working on a template?

As the aphorism goes, perfect is the enemy of good, so why not get started?

Later on I do think it would be a worthwhile exercise to consider what kind of content would be most valuable to the community. With this content publishing workflow, community members are free to contribute as they see fit. That being said, much like “good first issues,” I suspect curating a few topics might help newcomers feel invited to get involved.

As we head in to the Fall, we can devote time to better understanding the audience and identify a few common pain points or road blocks that would be high value for early content. These quick wins would help onboard new community members and give us some stories to celebrate the first contributors.

We can also develop a strategy to promote and measure the impact of the content and tell the story of how the community is influencing the outcome of what TBD is trying to achieve.

2 Likes

+100 to all of this.

I’ve been using your tutorial as a starting point to orient myself. The first couple health and dids queries looked great:

%> curl localhost:8080/v1/dids
{"didMethods":["key"]}

Got caught in the first write operation to add a DID:

%> curl -X PUT -d '{"keyType":"Ed25519"}' localhost:8080/v1/dids/key
{"error":"invalid create DID request"}

Has the ssi-service changed APIs since writing?

A great example of why I’m excited to do these tutorials/examples locked to a version and backed by tests!

Frank, should we start by setting up a repo for this with some scaffolding? I was planning to do that after I make it through a manual run, but if you want to get moving, I can create that repo for us so you’re not held up.

S,
ALR

Frank, I know you have a bit of time to work on this now. Where do you propose we start?

1 Like

And Gabe’s working on a fix for the issue noted above!

Fixed here Environment specific tracing config by decentralgabe · Pull Request #69 · TBD54566975/ssi-service · GitHub

2 Likes

Thanks! Could be user error if I didn’t get the changes built and deployed right?

Reopened where Gabe’s been fielding with same-day SLA; what service, highly recommend.

Error on new DID create operation · Issue #68 · TBD54566975/ssi-service · GitHub

Angie, we’d brainstormed a doc w/ requirements for the system. Do you mind if I put that in a public README of the new repo? It’s here:

GitHub - TBD54566975/tbd-tutorials: Tutorials and Examples for TBD Projects

That’ll get us going with a place to sync changes, do issue tracking, etc.

@alr I was running into the same error message after the tracer addition in commit 14d3a80.

I think I spotted the issue and posted some suggestions in Issue #68.

1 Like

@techgirl1908 @alr It would be great to start with any requirements you’ve already collected. For example:

  • Any existing site publishing tools preferred? For example, I see a Docusaurus version of the developers site, but it seems like it was only an experiment.
  • Markdown format? (vs. AsciiDoc)
  • TBD CI/CD toolchain preference

-Frank

thanks, fixed in the latest commit.

1 Like

good idea. go for it!

2 Likes

I came across my first requirements-gathering question:

Define Runtime Requirements for CLI tools and Scripting · Issue #1 · TBD54566975/tbd-tutorials · GitHub

Need ideas! I’m not yet certain how we should automate Frank’s sequences as shown in the tutorial so people can run a command like $> execute-tutorial make-schema or $> execute-tutorial make-vc or $> execute-tutorial run-all. Not to mention testing the output matches as expected! The programmer in me wants to have access to a proper language to do that in as opposed to platform-dependent tools and shell scripts. More context in the issue above. :slight_smile:

And I added some intent to the project README:

tbd-tutorials/README.md at main · TBD54566975/tbd-tutorials · GitHub

1 Like

markdown is a better format to stick with over asciidoc.

@alr left a comment on this on github.

I’ve always liked and preferred Asciidoc! Pretty subjective, IMO.

And it’s also true that most of the TBD docs are done in Markdown so for consistency I’ve been using it here too.

S,
ALR

Perhaps a poll in discord or the forum could show us what the community prefers.

An update from some of my exploratory work done this past weekend.

We’re threaded into the requirements:

  • Automated, so the examples can be run by the user as a script or CI service
  • Testable, via the automation and client validating expected responses

I still think these are important, because they protect the user experience.

Short-term, I think it’s appropriate to focus on the easy lift task of publishing the content into a Tutorials/Examples section on the dev site. Markdown > Publish.

WDYT?

Longer-term:

While working on the automation pieces to collate content and insert real code into it, I prototyped with several Markdown pre-processors and other docs tools so we could include files and or partial files into a main one. My thinking was that if we could make a main doc page for the examples, we could inject code, shell commands, etc into it, the same code/shell that’s automated and tested.

The things I looked at:

  • MarkdownPP (no longer maintained)
  • Pandoc
  • Antora, an Asciidoc doc site generator
  • Gitdown
  • Markdoc, derived from Stripe’s API Platform
  • Postman API Platform, one I initially overlooked because it’s not targeted to generate docs, but it does have a nice feature for showing how to call APIs in various languages/frameworks. Thanks to team for showing me that feature!

I don’t have a conclusion on an appropriate toolset yet. Does it make sense to y’all we continue as proposed above for a short-term salve to focus on getting content published, and continue working on the “publishing system” longer-term?

S,
ALR

1 Like

Some others to add:

Postman is great for demonstrating API calls. Agreed on testing and automation.
Other things to consider as well is which offers great accessibility features and language options given the global nature of the growing community.

Other questions:

  • What are some criteria in addition to what you listed to help narrow down on a tool? Ex. localization, accessibility, cost, code injection, etc
  • Does the community maintain the docs?
  • Where will the docs be hosted?
  • Or is there a plan to centralize with the tbd open source team and then decentralize it over time.