[Plugin] TechDocs / Docs-like-code

[leemills83]

Summary

Add easy to use technical documentation plugin to Backstage. Some inspiration can be found from our internal technical documentation:

Context

TechDocs makes it easy for you to make your team’s technical documentation available in a central place (Backstage) for other teams to discover. Treating documentation as code, you produce documentation within your software development workflow. You follow a few simple conventions and your documentation appears in Backstage instantly.

[stefanalund]

Since TechDocs is an internal name I think it would be better to name this issue something like “Docs-like-code” or just “Technical documentation”.

I also look forward to seeing what different pieces are required behind the frontend for this plugin to work 😀

[andrewthauer]

I've been thinking and experimenting a lot with a docs-like-code approach recently. I'm curious on the scope of what this plugin might provide though.

I know Spotify uses mkdocs internally. I looked at a lot of different static site generators and also settled on mkdocs because it seemed to provide the least configuration setup required for teams to use in their projects. In fact I've been able to hide it within the CI pipeline entirely so folks can focus on just writing docs and rely on conventions.

That said, I do think that any solution here should be agnostic to the tools to generate documentation (if possible). Integration with any existing tools that an organization may be using would be key for larger adoption.

Here is a list of "potential" areas of scope I see for this plugin:

• A catalog / inventory system that tracks various documentation sites that might be generated by different teams, repositories, etc.
• The front-end plugin that handles routing & rendering of documentation sites.
• A back-end search service that proxies search queries to something like elasticsearch. The results would then need to be mapped to appropriate deep links on different sites (which the frontend would need to handle routing for)
• Some sort of system that can update the search index when docs sites are updated/published.
• Common tooling to generate sites that "conform" to the contract that will work with the plugin tooling, catalog, index service etc.

Some other features that seem really useful would be:

• Analytics tracking.
• Knowing when documentation has been updated and providing notifications, etc.
• Ability to annotate docs with information from GitHub (e.g. open PR comments).

Also curious where the line is drawn for tools that content creators will be using to create documentation? Tools can be very opinionated and highly dependent on individual workflows & processes. However, it feels like the content creation experience is a key ingredient in how it might relate to the consumption of the content.

PS - Very excited about this plugin 😄

[SpamapS]

I don't know if this is directly related, or something that would be a separate feature or part of this, but a really neat thing that the Rust community does is that they run the example code snippets in their technical docs as tests. This prevents the problem of "the example doesn't work anymore" and is especially good for avoiding API breakage.

https://doc.rust-lang.org/rustdoc/documentation-tests.html

[Rugvip]

@SpamapS, yep! same thing in Go, https://golang.org/pkg/testing/#hdr-Examples

Never seen it implemented in JS/TS though, probably trickier since it's a dynamic language. It's a neat idea though.

Did just find this: https://github.com/yamadapc/jsdoctest 😁

[stefanalund]

A catalog / inventory system that tracks various documentation sites that might be generated by different teams, repositories, etc.

@andrewthauer I think we should follow the same model we use inside Spotify; i.e. treat documentation as yet another piece of software that is stored in the Software Catalog.

In such as setup there are two categories of documentation:

1. Docs only - stand-alone documentation site
2. Docs with code - documentation living together with an existing software component, e.g. a backend service or website.

[andrewthauer]

In such as setup there are two categories of documentation:

1. Docs only - stand-alone documentation site

2. Docs with code - documentation living together with an existing software component, e.g. a backend service or website.

@stefanalund - These make perfect sense to me and is how I've also been looking at it.

I wonder if there might be room for a 3rd more abstract option such as external docs? I suspect many organizations will still leverage other documentation systems/processes along with backstage (either transitioning or permanently). I have no idea how this would work, but being able to somehow integrate existing documentation systems into a central place like backstage could both help encourage a docs-like-code approach and avoid yet another documentation tool/process being introduced.

[stefanalund]

@garyniemen @emmaindal time to close this one?

[garyniemen]

Not quite. But soon. Our v1 milestone is an alpha version of TechDocs that works end-to-end. We have set a due date of 28 August.

[OrkoHunter]

With TechDocs v1 launched and progress being tracked by Backstage documentation, I think it is okay to close this issue. cc @spotify/techdocs-core @stefanalund @leemills83

[OrkoHunter]

Please re-open if you feel so. 🙇