Documentation & Other Files

[jamiebuilds]

One of the major ways that comment-based documentation sucks is for working with detailed guides and code examples.

I think we should really consider how we can make documentation better holistically rather than just focus on API documentation.

---

One of the patterns I've started adopting in several other tools is having a examples/ folder with a defined structure.

/package
  src/
  examples/
    0-basic.js
    1-advanced.js
    2-app/
      // whatever files & folders

Each of the files or folders operates in isolation and the source code is written as if it were totally separate from everything else (i.e. import 'package-name vs import '../src/index.js)

Using this file structure I can use it for documentation, a storybooks-like UI, testing, and more. Which is something that would be really hard to do if all my examples were embedded within comments.

For the documentation, it would be nice to be able to integrate guides with examples with api docs, mixing them together arbitrarily. Which can be manifested as:

• Links - being able to get references to API docs/examples/guides easily in ways that don't break and are validated
• Includes - being able to grab some part of the API documentation and being able to drop it in the middle of a larger guide

Tooling around this spec can solve most of the problem, but a clear way to handle this should be embedded within the spec itself imo.

---

One way that we could do this is to add a concept of "refs" which allow us to associate a unique identifier with a chunk of documentation.

/**
 * Description
 * @ref myImportantRef
 * @param foo {number} blah blah blah
 */
function bar(foo) {...}

This could then be validated as being unique and tools that lookup the ref could easily assert that it exists. It also doesn't need to change as your code changes.

---

I don't have any other ideas right now, I'll keep thinking about it, but I'd like to hear how else we could improve the experience integrating guides and examples better.

[tmcw]

Sure, so...

JSDoc has a whole tutorials system, which is not implemented at all by documentation.js. Documentation.js's 'table of contents' does allow some room to add longer-form documentation, but I see some breaking point for more broad support: if you go far enough, you're recreating a static site generator, and we know from gatsby etc that that's a whole 'nother large problem area. I've been hesitant about supporting 'guides' for that reason - I've never seen a way to do it that doesn't blow up the scope of the project.

I'm very interested in better ways to solve this problem - some projects like next.js have really demonstrated that 'an example for everything' is an effective teaching strategy.

Some thoughts here:

• Could we support a src link strategy as part of the interlinking strategy (#4) - [[JSON.stringify]] would magically link the named thing but [[../examples/foo/]] would link to & verify the existence of a path there? This would hotlink GitHub, at least initially. Raises the question of whether examples need to be something more elaborate than just directories to browse under github.
• Re: the grabbing documentation question - maybe for stuff like gatsby, we could provide a graphql endpoint?

[jamiebuilds]

if you go far enough, you're recreating a static site generator

To be clear, I don't want to do that. I think the "result" of this spec should be JSON. But when we go to do things with that JSON, we can have hooks in there for various purposes.

Links to documentation in other modules:

/**
 * Calls [`moduleMethod`](npm:module-name#moduleMethod).
 */

Note: dx will lookup module-name version from package.json and turn this into a permalink which could be routed through a service we could put up on https://js.org/

{
  "description": "Calls [`moduleMethod`](https://docs.js.org/module-name@^1.0.0/moduleMethod)"
}

Exposing references:

/**
 * Important method
 * @ref importantMethod
 */

{
  "refs": ["importantMethod"]
}

Example and docs refs

/**
 * Important method
 * @example examples/foo/bar.js
 * @tutorial docs/foo.md
 */

Note: I think it would be better for these to be links rather than inline examples.

{
  "examples": ["examples/foo.js"],
  "docs": ["docs/foo.md"]
}

And whatever we can think of.

[ELLIOTTCABLE]

I love this. I'm right there with @thejameskyle — if this repo is for a specification for a syntax and semantics to go with that syntax, it's fairly easy to delineate implementation-lines — what a given generator will (and will not) do; or even a way for a chain of seperate tools, seperate areas of concern, can handle in concert. Thus, this should be included in the spec.

---

Now, while I'm all for more explicit orchestration of code-blocks with non-code-block documentation … I have to say I'm staunchly against the idea of @ref, or anything like that.

As I've championed in documentationjs/documentation#857, and just detailed a few moments ago in #4 and #9 — I strongly believe that we should be using a combination of deterministic rules (for identifiers — the only part relevant to this spec), heuristics (for references to those identifiers), and static analysis (We Have The Technology™!), over explicitly requiring documentation-writers to constantly continue thinking in a higher-level way about “links” and “resources” when writing documentation. Just write code in your documentation, don't write meta-documentation in your documentation!

tl;dr instead of “eh we won't be able to understand you if you say what you mean, just always say a different, explicitly-clear thing, also by the way remember to think up that-other-thing every time you make something new, also by the way always remember that-other-thing in addition to remembering the thing you probably meant, everywhere, for the rest of the life of the project, whenever you're writing about it, also remind other collaborators about the-other-thing” … I think we should optimize for “say what you mean.” Y'know?