Adopt a framework for documentation

[gwhitney]

From the conversation on #69, there's clearly a need for a place to put such information as the code style guide, which is of documentary interest both to the core team and to potential new contributors. We also have a stub of a user guide integrated into numberscope itself, which includes, for example, usage documentation on each Visualizer (except some are stub or missing). To satisfy these and other documentation needs, the project should adopt a framework for where documentation will be kept and how it will be organized.

[gwhitney]

I absolutely agree with the stub design that (at least a portionf of) the documentation should be available right from the Numberscope itself. So one basic question: (A) should the documentation so accessible comprise all documentation, including for example the contributing guidelines and coding style guide? Or should there be a user guide limited just to how to make nice pictures with Numberscope and maybe the theory behind the various visualizers, with more technical/code information available "somewhere else"?

[gwhitney]

The next basic question is (B) how should we capture that documentation? Should it be in the main repository itself, or (some or all of it) be in a place like a GitHub wiki? In the former case, what format should the documentation be in? Depending on the answer to (A), there might be two different answers here, one for each division of the documentation.

[gwhitney]

And the third question is (C) how should the documentation be provided to interested parties? Again, the answer(s) could depend on the answers to (A) and (B). For example, if some goes into a wiki, then that content would be served by GitHub's wiki feature.

[gwhitney]

Now that I've attempted to lay out the issue and its component questions objectively, I will say what my leanings are:

For (A), I think this project is small enough that all documentation should be clumped together, just presented so that user-guide type stuff is more easily accessible to someone just playing with the 'scope, but with readily apparent links for those who want to dive deeper.

For (B), we currently have what user guide information there is in a Vue view. While that makes (C) -- serving that information -- completely trivial, it seems to me to be a fairly cumbersome format in which to author documentation. There is also a philosophy (that I subscribe to) that documentation should be alongside the code it is documenting rather than off it a separate place, as is currently the case. The alongside-approach facilitates such things as requiring any PR that adds a Visualizer or changes the behavior of one to include the new or changed documentation. This approach splits into two main options: VisualizerDifferences.ts is documented in VisualizerDifferences.md that lives next to it in the same directory; or the documentation for VisualizerDifferences is literally extracted from content in VisualizerDifferences.ts, typically in some form of structured comments. Then documentation that does not cohere to any particular source file, like the coding guide, would be in a separate docs directory.

Finally for (C), I would suggest one of the systems for collating all of the documentation in the various places (the alongside-files or extracted from the source files, together with the dedicated documentations files) and producing a nicely-formatted static website; the build/installation process for Numberscope would then simply include all of those pages in the site it produces, and the Numberscope app would have the appropriate links into that static portion. There are several mature systems out there for doing this sort of thing; I am most familiar with, and have the most experience with, the mkdocs system (https://www.mkdocs.org/), in particular mkdocs-semiliterate (http://studioinfinity.org/semiliterate/), which is the sourcefile-extraction flavor of mkdocs.

[gwhitney]

Anyhow, @liam-mulhall and/or @katestange it would be great to have your opinions on these matters. Certainly I won't do anything to move toward a documentation framework until we've reached some sort of consensus on how to proceed. Thoughts and suggestions are welcome from everyone who has access to this repository, of course!

[gwhitney]

I realized that for counterpoint I should mention at least one other documentation generator. So another example is JSDoc (https://jsdoc.app/) -- I am not so familiar with it, and am not sure how suitable it is for both a user guide and for technical/interface documentation (it seems more designed for the latter). But note that in many of the visualizers there are already some instances of JSDoc-style structured comments, so it's probably worth at least contemplating formally using JSDoc.

EDIT: I looked over the JSDoc site a bit more, and JSDoc does allow arbitrary "tutorials" in addition to the straight documentation of your classes, functions, etc. So it seems we could use it to generate the User Guide as well. Thus, either mkdocs or JSDoc would be alternatives for creating static documentation, and there are certainly others out there. In fact, there seem to be some specifically for TypeScript (see https://blog.cloudflare.com/generating-documentation-for-typescript-projects/).

[liammulh]

@gwhitney, I'm happy to use http://studioinfinity.org/semiliterate/. I think it would be good because it allows us to use the same documentation system across the repos.

[liammulh]

Related to https://github.com/numberscope/frontscope/issues/127, https://github.com/numberscope/frontscope/issues/69, and https://github.com/numberscope/frontscope/issues/73. (Presumably, the site where we put our documentation would have all of this.)

[gwhitney]

Does @katestange have any opinion on the documentation framework? I am certainly not going to vote against the system that I use for all of my self-organized projects. If there is a decision to adopt semiliterate, then I (a) need to update it to the latest version of mkdocs/mkdocs-simple-plugin (already on my list, but I would bump it up in priority), and (b) would be happy to do an initial pass at setting up semiliterate and generating static documentation pages.

[katestange]

I've just re-read the thread here. I will defer to those with more experience on the exact documentation framework, and would tend to trust your instincts/preference for semiliterate. I will just point out some of my priorities, and ask if these will be served: (1) I would like there to be copious user-friendly documentation for using the website and using the visualizers. This should be easily findable/accessible to non-tech-savvy users and not encumbered by technical stuff mixed in too much. So if we pull all documentation from inside the code, I'm imagining there will be long headers in the visualizer files (for example) that will just be markdown of a narrative friendly user guide that will appear before any localized code documentation for functions within the code etc. Is my imagination correct? (2) I would like it to be easy for writers of visualizers to document them; e.g. maybe a template and instructions are included for how to do this easily. Whatever we choose should not make that aspect harder. So, given these priorities, do you foresee any issues?

[gwhitney]

1) Absolutely. What I've been suggesting is that we use a documentation framework to create static webpages that have all of "user guide", "make your own visualizer intro", and "technical docs" in an easily navigable format, and then just serve those pages along with the visualizer app, with appropriate links from the app to those pages. The reason I like semiliterate as that framework it that it is good at extracting such documentation from arbitrary source files, so indeed, a visualizer source file can start with its "user guide" markdown (inside TypeScript comments) and then have its code, potentially interspersed with tech documentation as necessary. I think that fits your vision aka "imagination", yes?

2) Indeed, either the base visualizer class should serve as a template with instructions for creating and documenting a visualizer, or we can pick one actual one as the exemplary one and link to it from the general instructions.

So I don't foresee any issues. Absent any further objections, I will plan to install semiliterate and get at least stubs for all of these pieces in place, once the Vue 3 merge is complete.

[katestange]

Sounds great! Thanks!

[liammulh]

Since @gwhitney has plans to work on this, I'm going to un-assign myself.

[gwhitney]

Preparing to work on this soon; just want to check that @katestange and @liam-mulhall are OK with moving all of "About", "Acknowledgments", and "Help" from being Vue components to being pages in the static doc site (linked to from the Vue app as appropriate, of course).

[liammulh]

I'm okay with this.

[katestange]

I'm ok with it too.

[liammulh]

Once the documentation system is established, we should add instructions on how to add documentation to the merge review checklist. See https://github.com/numberscope/frontscope/issues/99#issuecomment-1179869041.

[gwhitney]

Implemented by #139, closing.