search

TBD54566975 / tbd-tutorials

Tutorials and Examples for TBD Projects
Apache License 2.0
4 stars 4 forks source link

[RFC] 1 WIP: Docs as Code #4

Open frankhinek opened 2 years ago

frankhinek commented 2 years ago

Summary

Proposal to adopt a docs-as-code approach for developing a technical documentation system that helps orient newcomers, helps contributors acquire and apply knowledge, and helps create an inclusive community.

Context and Scope

TBD's projects are developed in the public guided by an open source philosophy with three foundational pillars: inclusivity, transparency, and clarity. This proposal is focused on making progress towards fulfilling these commitments:

  • Anyone with the capacity to contribute: can.
  • We are proactive in welcoming a diverse contributor base for our code, documentation, ...
  • Decision-making is open by default, ...
  • Projects need ... accessible, comprehensive documentation, a stellar Getting Started experience, and well-defined expectations.

"Incomplete or confusing documentation" has frequently been cited as one of the top problems in open-source software development. Accurate, up-to-date, and well-organized documentation improves the first time contributor experience, creates a more inclusive environment, and can result in significant productivity boosts.

Given the target audience for developer.tbd.website and early stage of development for most TBD projects, it follows that the documentation should be optimized for the new contributor experience. Using a docs-as-code approach combines the power of developer tools with techniques to encourage community engagement and improve documentation quality.

Treating docs-as-code means that document publishing follows a similar process to software development:

By taking an open approach that is accessible and familiar to developers, TBD can establish a virtuous cycle by encouraging more community enhancements and feedback to improve the contributor experience, which in turn leads to more engagement.

Goals

Non-goals

Several of these could reasonably be goals, but are explicitly chosen not to be goals in favor of releasing a minimum viable documentation system and receiving feedback from the community.

Proposal

Document Format

Documentation Processing

Repository Structure

Documentation Flows

Document publishing follows a similar process to software development:

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':false,'mainBranchName': 'main'}} }%%
      gitGraph
        commit
        commit tag:"Create Branch"
        branch new-topic
        commit
        commit
        commit type: HIGHLIGHT tag:"Open PR"
        commit
        commit
        commit tag:"Review & Improvement"
        commit
        checkout main
        merge new-topic tag:"PR Merged"
        commit
        commit

Authoring New Content

  1. Contributor forks the TBD community docs repo on GitHub and creates a new branch.
  2. Contributor creates the directory structure scaffolding for a new tutorial.
  3. Contributor authors the document, including any command/code and/or images.
  4. Contributor opens a pull request (PR) in the TBD community docs repo.
  5. TBD and community members review, manually test command/code examples, and provide feedback.
  6. If approved, the PR is merged to the TBD community docs repo.
  7. GitHub Actions automatically process the contributed docs and open a PR on the TBD Developer Site.

Suggesting a Fix or Improvement

  1. Contributor opens an Issue or PR in the TBD GitHub repo.
  2. TBD and community members review and provide feedback.
  3. If approved, a PR is created (if starting as an Issue) and approved/merged.
  4. Automated workflow publishes the revised content.

Definition of success

Open Questions

  1. After a community contribution is approved and merged into the community docs repo, a GitHub Action will automatically create a PR in the TBD Developer Site. When this action is creating the PR, should it create a new branch and PR for each approved push to the community docs repo? Or should any additional pushes to the community docs repo main branch be added to the open TBD Developer Site PR until it is approved or closed?

Appendix

Alternatives Considered

Design Decision Rationale

Why Remark?

Why encapsulate utility tools/scripts with Docker?

Decision Log

  1. Docusaurus is used for developer.tbd.website, which supports MDX. Should we support including JSX in markdown content for community-contributed docs?

    DECISION: MDX/JSX will not be supported in the initial release.

    Additional Context: There may be complications related to how Docusaurus handles MDX and incorporates external Markdown. Long term we may want to offer docs authors greater flexibility in styling by exposing JSX directly. In service of MVP, we will limit the scope to exclude support for community contributors authoring MDX and release a system which lets us author in Markdown, embed code and images and publish content on the TBD Developer Site.

  2. When new documentation is approved and PRs merged, GitHub Actions can be triggered to build the doc artifacts and potentially trigger publishing to developer.tbd.website. Should this workflow run in the main Docusaurus site repo or the community-contributed docs repo? What additional steps can we take to automate the publication process and minimize human intervention?

    DECISION: The community-contributed docs repo will use GitHub Actions to build the output Markdown and trigger a Pull Request on the TBD Developer Site repo.

    Additional Context: The community-contributed docs repo can run builds to compose the output Markdown, and then we trigger a PR into the Developer Site repo to update/add the newly-generated page? This would let us always revert the Developer Site if we needed, and makes clear when a new piece of content is to be published, while letting the docs repo handle its own build to generate the markdown.

ALRubinger commented 2 years ago

This is a remarkable effort. Thank you, @frankhinek!

Overall, it's a path I'd love to continue exploring. I appreciate the Docker-based approach to lock the build environment and give devs consistency. Remark looks like it's working great so far for the code injection and templating. My run through the docs here got me a clean build with no issues and the sh snippits inlined into the output. Overall, I'm really curious to see how this works if we do automate this into a PR for the developer site - I think that'll be proof that we're on to something. As you call out, the workflow is super important to contribution and to our validating that we've really lowered the bar to docs submissions from folks. TL;DR from me is I think this makes a lot of sense to make progress, and I suspect we'll have plenty of room to fine-tune along the way.

Some more detailed feedback on items in the WIP:

Non-Goals

Is the intent here simply to keep scope small to deliver an MVP?

Automated testing, to me, is the piece that protects user experience by making sure that the docs as published will work against a specified version of the software. Are we leaving space for this to be solved later, or do you have opinions about the testing of docs that leave this out of scope longer-term?

One of the best ways I've found to welcome new contributors is to give them an easy way to translate docs into their preferred language, in turn addressing a more global audience and welcoming them. Same question as above: we'll leave space for this to add easy internationalization so that docs can be prepared in N outputs, pulling in the same code snippits that you've externalized in this example?

Open Questions

This one may get murky as I believe it's tied into how Docusaurus handles MDX and pulling in external Markdown. Long term we may want to offer docs authors greater flexibility in styling by exposing JSX directly. In service of MVP I'd be thrilled to start by releasing a system which lets us author in Markdown, embed code and images as you've shown, and get things published on the Developer Site. WDYT?

Hot takes: chained builds? The community-contributed docs repo can run builds to compose the output Markdown, and then we trigger a PR into the Developer Site repo to update/add the newly-generated page? This would let us always revert the Developer Site if we needed, and makes clear when a new piece of content is to be published, while letting the docs repo handle its own build to generate the markdown.

Will also comment on the forum post about this to address how we wanna keep the momentum up here. @frankhinek - thank you again!!

saeedjabbar commented 2 years ago

@frankhinek Excellent job. See my write up here: https://forums.tbd.website/t/tutorials-and-examples-system/89/25?u=saeedjabbar

frankhinek commented 2 years ago

Overall, I'm really curious to see how this works if we do automate this into a PR for the developer site - I think that'll be proof that we're on to something. As you call out, the workflow is super important to contribution and to our validating that we've really lowered the bar to docs submissions from folks.

Agreed -- wiring up the workflow end-to-end will help to validate the approach, and we can work out any minor issues along the way. To accelerate the implementation and testing we could create a second repo to simulate the developer.tbd.website Docusaurus integration (GitHub Actions & PRs). Once the approach is validated and the contributor experience is satisfactory, the workflow can be incorporated with the repo tied to the production deployment.

Is the intent here simply to keep scope small to deliver an MVP?

Automated code/command testing and linting

Yes, precisely. The intent was in the spirit of getting an MVP going per the forum discussion thread. As I started writing out the detailed design proposal, it became clear that getting the contributor experience right with automated tests was going to take some iteration. There are a few ways to approach both in-lining the statements and authoring tests, which can be decoupled from the initial MVP deployment.

I do suggest that we tackle this in the near-term as it does have numerous benefits for the contributor experience. "Broken" step-by-step documentation is all too common, particularly for fast moving projects. Additionally, the longer we wait to introduce this feature, the more clean-up work will be needed to address previously published content.

Multi-language support Same question as above: we'll leave space for this to add easy internationalization so that docs can be prepared in N outputs, pulling in the same code snippits that you've externalized in this example?

That is a great point and could be a good way to encourage more early contributors. Based on a review of how Docusaurus handles i18n, it appears that this would be fairly easy to plan for in the initial design and incorporate in the short-to-medium term depending on the prioritization by the community and TBD.

Q: Does the current developer.tbd.website Docusaurus instance already have i18n configured, and if so, can you share a few details that can guide how to structure community contributed docs?

e.g., translation file structure, single-/multi-domain strategy, etc.

Should we support including JSX in markdown content for community-contributed docs?

In service of MVP I'd be thrilled to start by releasing a system which lets us author in Markdown, embed code and images as you've shown, and get things published on the Developer Site. WDYT?

Agreed -- progressing to an initial working MVP seems appropriate.

Should this workflow run in the main Docusaurus site repo or the community-contributed docs repo?

Hot takes: chained builds? The community-contributed docs repo can run builds to compose the output Markdown, and then we trigger a PR into the Developer Site repo to update/add the newly-generated page? This would let us always revert the Developer Site if we needed, and makes clear when a new piece of content is to be published, while letting the docs repo handle its own build to generate the markdown.

I like it for the reasons you highlighted, and it also allows the two to run in parallel at a different pace, if needed.

frankhinek commented 2 years ago

Updates:

End-to-end Worklow Notes

Two repos are used to mock the TBD Developer Site and the Community Docs repos:

The steps for authoring new content are:

  1. A contributor would start by forking the TBD Community Docs repo, cloning locally, and adding/editing content.
  2. There's now a Live Preview utility so contributors can see how their content will look once its published: tbdoc Live Preview.
  3. Once satisfied with their additions/changes, a contributor commits their changes to their fork and submits a PR to the TBD Community Docs repo.
  4. TBD and community members review, and if needed, provide feedback or request changes.
  5. Once the PR is approved and merged to the TBD Community Docs main branch, GitHub Actions automatically kicks off an Open Dev Site PR workflow to process the Markdown content and open a PR in the TBD Developer Site mockup.
  6. The TBD Developer Site PR contains the committed files, a link to the original approved merge, and also a Netlify Deploy Preview for the team managing the TBD Developer Site to review the visual appearance of the contributions.
  7. If the changes are accepted, the PR is approved/merged and then the typical publishing process for the TBD Dev Site would kick off.

Here's an example:

ALRubinger commented 2 years ago

This is amazing. Thanks for the patience while I've found the time to grok the comprehensive docs and instructions you've laid out here. All ran great here and I totally see where you're going with this workflow. Eager to get it into the repo and hook things together, and I've granted you admin access here.

I've written up some more details on the forum thread.

To your open questions:

Docusaurus is used for developer.tbd.website, which supports MDX. Should we support including JSX in markdown content for community-contributed docs? This one may get murky as I believe it's tied into how Docusaurus handles MDX and pulling in external Markdown. Long term we may want to offer docs authors greater flexibility in styling by exposing JSX directly. In service of MVP I'd be thrilled to start by releasing a system which lets us author in Markdown, embed code and images as you've shown, and get things published on the Developer Site. WDYT?

Exactly as you suggest. Let's get some Markdown where we can embed code and images and iterate from there. That alone is a huge win for bootstrapping contribution and getting it published.

When new documentation is approved and PRs merged, GitHub Actions can be triggered to build the doc artifacts and potentially trigger publishing to developer.tbd.website. Should this workflow run in the main Docusaurus site repo or the community-contributed docs repo? What additional steps can we take to automate the publication process and minimize human intervention? Hot takes: chained builds? The community-contributed docs repo can run builds to compose the output Markdown, and then we trigger a PR into the Developer Site repo to update/add the newly-generated page? This would let us always revert the Developer Site if we needed, and makes clear when a new piece of content is to be published, while letting the docs repo handle its own build to generate the markdown.

Love the chained builds approach and it's given me success before. Because: then we've cleanly decoupled the docs contribution piece into its own workflow, and the publishing step will show us in each commit exactly what's to be pushed live on the dev site. Also makes for a super clean audit trail in the case we need to roll back changes on the Dev Site. I'm hoping this is a really easy contribution path for people by letting them focus only on the writing and docs generation, knowing the grander details of publishing will just (waves magic wand) be handled for them through automation.

@saeedjabbar had an open question too:

Q: Does the current developer.tbd.website Docusaurus instance already have i18n configured, and if so, can you share a few details that can guide how to structure community contributed docs?

Docusaurus has i18n support but we're not taking advantage of it yet, and I'm thinking that once we get this plugged in, i18n is an awesome thing to enable and let the community run with for translations. I was once astounded at how eager folks were to translate the Arquillian Quides into so many languages.