Documentation Tool Evaluation Notes

[kalisjoshua]

This is an early POC and documentation of goals in an ADR for discussion.

[switzerb]

I made a comment in the chat about this but I think it is worth addressing audience as a part of the requirements. It is a nice sanity check on decisions that get made to ensure that multiple perspectives and roles are getting addressed and can access/use/contribute to the docs.

• Designers
  Making the systems more transparent and consolidated will allow designers to improve and integrate new designs and make efforts more efficient and targeted

• Application Developers (Jeric2o, Hawkeye, etc)
  As the consumers of the platform resources, enabling easy access and clear documentation on how to leverage what is available will help developer velocity and adoption.

• Platform Developers
  As builders of the platform, devs will have a clear channel for explaining how and why the resources should be used, reducing mental load on communication strategies

• Onboarding Developers and Designers
  Onboarding people will be simpler because there will be a consolidated way to communicate a lot of context and the ability to reference important materials

• Product Owners and Managers
  Access to understanding the up to date capabilities makes it easier to plan and integrate the tools that are available into the existing product systems

• Business Stakeholders
  By having a clear overview of the capabilities and systems that are in usage, it is more possible to see the 30,000 foot view and conceptualize places to scale and grow

[kalisjoshua]

What are/were your thoughts around "worth making sure whatever is chosen works across the board even for non-coder types"? Do you mean the documentation content (end result) or more the editing and maintaining of the content?

[switzerb]

I was referring to contributions specifically. The technical bits of the docs are important, but ultimately the docs are only as good as the content...and a lot of the content will be "business" content that is owned by designers or potentially technical writers. But it looks like most of these use MDX or markdown text files so that seems doable.

[kalisjoshua]

Markdown (and similar i.e. MDX) was an unofficial requirement for me I think.

[kalisjoshua]

I've been working with RSPress for the past few days and I did get it to nearly be doing what we would want it to be. Specifically, it has built-in support for rendering React components but not Javascript/TypeScript "previews" (playgrounds) so I've been working on putting that together. I've successfully integrated the Monaco Editor, which is nice, but getting full support for the modules - meaning that false errors aren't represented - is going to be considerably more difficult; maybe that's why no one else has already done it. I was looking into RunKit but wasn't getting it working immediately, I might return to it; however, I do think that it requires that the modules to be used will need to be published which poses a problem for getting things working before publishing.

[belsrc]

I was looking into RunKit but wasn't getting it working immediately

Can you expand on that a little? It should be as be something like

<script src="https://embed.runkit.com" data-element-id="my-element"></script>

<div id="my-element">
var getJSON = require("async-get-json");
await getJSON("https://storage.googleapis.com/maps-devrel/google.json");
</div>

To get it spun up. Is it "where in the pipeline to inject the snippet" the problem or something else?

[kalisjoshua]

I was looking into RunKit but wasn't getting it working immediately

Can you expand on that a little? It should be as be something like

<script src="https://embed.runkit.com" data-element-id="my-element"></script>

<div id="my-element">
var getJSON = require("async-get-json");
await getJSON("https://storage.googleapis.com/maps-devrel/google.json");
</div>

To get it spun up. Is it where in the pipeline to inject the snippet the problem or something else?

When I was experimenting, adding the script tag wasn't working at all. It wasn't showing up in the rendered page and there was no network requests in the dev-tools requesting the resources from RunKit.

I also don't think we actually need RunKit specifically because everything we are building is not relying on Node.js APIs at all and therefor can be run in the browser just as successfully as it would anywhere else. Additionally, using RunKit would require that whatever we want to run in it be published and available which limits our ability to test unpublished modules.

[switzerb]

One thing I don't see in any of the criteria is search or any kind of discoverability. One of the most difficult parts of docs is finding what you are looking for -- did RSPress have any kind of indexing at all? If we wanted that would we have to build our own plugins?

[switzerb]

One other requirement that seems reasonable is that whatever we chose, the content shouldn't be "locked" into the platform. Like with Sharepoint it is nearly impossible to move content out of sharepoint and into another context. Although I suppose if most of the writing is in markdown, then that should be open enough.

[kalisjoshua]

Search is supported "out of the box".

Great question! And of the "top" contenders search is supported equally I would say.

[belsrc]

When I was experimenting, adding the script tag wasn't working at all. It wasn't showing up in the rendered page and there was no network requests in the dev-tools requesting the resources from RunKit.

Interesting. I would need to take a look at that.

I also don't think we actually need RunKit specifically because everything we are building is not relying on Node.js APIs at all and therefor can be run in the browser just as successfully as it would anywhere else. Additionally, using RunKit would require that whatever we want to run in it be published and available which limits our ability to test unpublished modules.

It's not really about Node APIs or not. Its more of having a REPL to interactively using the module in question. Like Lodash and, I believe, Rambda have. Unpublished part is not really a concern to me. If it is not published, no one can use it. No documentation needed. No REPL needed.

[kalisjoshua]

It's not really about Node APIs or not. Its more of having a REPL to interactively using the module in question.

We can a accomplish a REPL very simply without RunKit; I created a Javascript-only POC in a few hours including the specific lib dependencies. The challenge comes with including TypeScript features in an editor but even that is very accomplishable with something like StackBlitz and some additional config.

[belsrc]

I created a Javascript-only POC in a few hours including the specific lib dependencies.

Why add more maintenance overhead when something already exists?

[kalisjoshua]

Why add more maintenance overhead when something already exists?

Why add a dependency and potential security vector to avoid a very simple function?

[belsrc]

I'm going to go out on limb and say "making an in page repl" is not just a "simple function". And OSS packages are usually more secure then one persons NIH implementation. Coming from a strict security oriented stand-point.

And, from you initial comment, you are already pulling in libs for it so the comment is kind of moot.

[kalisjoshua]

We will use a dependency for the editor - monaco, stackblitz, etc. - because they are going to provide a whole lot of functionality for little investment. Using RunKit (or something like it) gives little functionality - and unnecessary limitations - for relatively more investment - than a local solution - and include a performance impact as well. I just don't see the return on investment for the REPL specifically.

As an example, here is the whole implementation of a "RE" of REPL where something like rspress provides the "PL".

// Option 0 - using `with`
const useWith = (context, code) =>
  new Function("ctx", `with(ctx) return (${code.toString()})()`)(context);

// Option 1 - if there is an avoidance of using `with`
const dynamicContext = (context, code) =>
  new Function(
     // `{${Object.keys(context).join()}}`,
    `{${Reflect.ownKeys(context).join()}}`,
    `return (${code.toString()})()`,
  )(context);

// context build from the repo packages and anything else special for examples
const context = {
  a: 123,
  foo: {
    bar: "bar",
  },
};

// the function is the code that would be "example" code and
// would be editable by users in the documentation site pages
useWith(context, () => foo.bar);
dynamicContext(context, () => foo.bar);