Dr Docs plan

[rcoreilly]

Here's some random thoughts about documentation strategy.

Principles

• Minimize need for custom text, emphasize examples (most people use copy-paste programming), and easy access to go.dev API docs. Interactive, editable examples would be the best.
• CORE principles: only one source for any given doc (preferably in docs/*.md), and make the doc content available on a standalone website and "live" within the app, using the same code.
• Basic hyperlink principles: any given '.md' doc can easily link to any other doc element (including pkg.go.dev docs for any given element or topic).
• Should be easy to write these links using [[shorturl]] syntax without making user enter full URL and associated label -- label should auto-generate as well as the full URL.

Specific ideas

• dr = doctor is the package name. short :)
• Top app bar overflow should have Help menu action with About and Help Browser submenu entries (latter enabled by including dr package).
• About shows the basic info about version, github hash, build date -- this same info is also shown in the crash log. Could also have link to "update available" or "latest version" kind of thing. This is the key info that users need to report if they have an issue.
• HelpBrowser is a Widget (dr.Browser) with a Splits: TreeView on left, CoreDOM on right, where tree shows list of help topics, and current topic contents on right. TreeView items have Label and URL for content to be displayed in CoreDOM.
  This is the main thing that dr provides, and it can be used both within any given app, and as a component in a webcore website. Shift click on treeview shows CoreDOM content in a new window -- e.g., for tutorials that you can then follow along with.
• Note that pkg.go.dev has this same structure -- should we somehow package and serve that same content within one single unified Browser interface? We could then embed active links to other non-api content in code comments using [[link]] syntax..
• To config the Browser, you just need to provide the treeview config. Can specify e.g., docs/ to automatically grab all the docs *.md files (md automatically rendered in CoreDOM) including subdirs etc. Can also manually specify these to get a non-alpha logical sort order.
• Simple default config would be: main README.md, pkg.go.dev/*, docs/, examples/.
• docs/*.md files provide the bulk of the non-api docs for cover basic stuff like install, overview, news, status, tutorials, etc.
  Each page can use [[label]] to generate a link to another page in the same Browser space.
• Figure out how to make the examples/ runnable (and editable via link that pulls up Cogent Code) directly in the Browser, either when calling from the App or on the web page. Use the wasm plugin idea here?
• Enable nested dr.Browsers so you can have a meta Cogent browser that can drill down into any specific apps or core browsers.
• Should interoperate with webcore so dr.Browser is an element of a larger website. Need a design spec for webcore. Could it just be the same as Browser? I would like a tree in general for any kind of organized website content -- blogs often have this (on the right instead of left?). Of course tree needs search element on top -- we should have a good example of that and support filtered TreeView view as well.

A key testcase for this will be these sims: https://github.com/CompCogNeuro/sims -- if we can just have a standalone website that you can browse and run all the sims from, that would be so much simpler. That would require webgpu working though. Maybe we can use hashicorp as alternative when running outside of web? Anyway, this is the "gapp" domain.