Suggestion for documentation overhaul

[CAYdenberg]

First of all, this is a great project. Major props to everyone who worked on it, I think the very quick response in terms of how much I'm seeing this come up in my feeds speaks to how much something like was needed.

I do think that the documentation, specifically the "big picture", needs some TLC to make it clear who this project is for, what the "boundary conditions" are, and developing an accurate mental model in the mind of the consumer. Again, this is no slight against the developers; all of this likely comes down to "proximity blindness".

Broadly, the problem with the docs is 2-fold: there is lot of information crammed into Getting Started, after you scroll through a lot of guidance on the startup scripts (likely unnecessary, since it's intended to make it very easy to create a project). If you miss this bit, much of what follows is hard to grok. Secondly, the "bulk" of the docs (according to the TOC) is quite detailed: a long list of inputs, a long list of libraries, and some CSS; however, each of these sections is missing general information. For example, you have to look elsewhere to figure out how the inputs bind to the JS runtime (using view).

What's needed is to expand the layer between the intro and the details, organized by what people are likely to be looking for. If I want to change the theme, I need to know what my options are, whether that's picking a different pre-built theme, writing my own CSS, or changing the header/footer HTML.

Here is proposed, modified outline:

• Introduction (what is this for?)
• Getting Started
  • Installation/startup script
  • Markdown and routing
  • Data Fetching and display
  • Publishing to Observable
• Core concepts
  • Reactive JavaScript
  • Displaying Data (inline and block rendering, display and view functions)
  • Fetching Data (building, cache/invalidation, output formats, use of stdout/stderr), use of FileAttachment
  • Imports and components
  • Styling/customization (themes, CSS, toc options, search, overriding HTML)
• API
  • CLI
  • Config
  • Reactive JS details (promises, generators, mutables)
  • Exact markdown spec (include stuff like tables, run=false to show codeblocks)
  • Inputs
  • Built-ins (include the current list of "libraries" as well as other stuff that's built-in, like the practice datasets)
  • Observable-supported languages for loaders
  • Publishing to "whatever" and setting up CI/CD

Obviously these are not exact titles in all cases. I think this layered approach would make it much easier to figure out the basics of how to use Framework, and let the details be details.

[mbostock]

This is great feedback, thank you!

[mbostock]

Working on this now in #1187.

[mbostock]

We’ve landed a fairly substantial restructuring in #1187. Please take a look and let us know what you think. Thanks again for the feedback.

[CAYdenberg]

Cool. Will look soon.