Docs Refresh Plan

[kourge]

This relates to #82. Documentation on nion is difficult to navigate, and often results in users old and new being forced to read the source code of nion. Here is a plan to solve this by streamlining the docs.

At the center of this refresh is a single Markdown file that is designated the Walkthrough. The Walkthrough is what the README file should link to at the end of the "In a nutshell" section. It should:

• better reflect the journey of someone new to nion
• serve as a much more cohesive index to various topic for existing users of nion

In essence, it's a fancier version of the index to the ./docs directory.

Note: all links to the repo are pinned to the SHA-1 95ffcdcc3123c3b0f2483e1b28f6fcd9a5a8daba, which is master at the time of writing.

Overview

1. Rename Getting Started to "Setup and Configuration". This doc is not a required read for someone working on a codebase that already uses nion.

2. Create the Usage file. It will illustrate the three forms of nion: hook, HOC, and decorator. See #110 for work in progress.

3. Create the Walkthough file. Its tentative name is index.md and its tentative H1 heading is "Getting Started on nion".

   • H2: "New to nion?"
     • Check out Usage, Declarations, Examples, Core (shallow)
   • H2: "Hello, old-timer"
     • Check out Glossary, Core (deep), and other in-depth stuff

4. Merge nion api into Declarations.

   • Clearly illustrate which declaration options are common, unique to hooks, or unique to HOC.
   • Verify each option's Required status and fix where necessary.
   • Reorganize the three declaration forms — function-returning-object, object, string — as a cascade of syntactic sugar.
   • Sync with #107 to ensure that the description of various options is consistent.
   • Docgen stretch (see section below for details)

5. Create a hooks version of Examples.

   • Verify that all existing examples are valid
   • Rewrite existing examples to use the plain HOC syntax instead of decorators
   • Produce hooks-equivalent examples

6. Merge How nion works into nion core and rename to "Internals". Both pages document nion internals; they differ by how deep of a dive they take the reader. Divide the page by section to delineate shallow snorkeling from deep dive.

7. Ensure Glossary is up-to-date

   • Sync with #107 to ensure that the type names therein match the terms in Glossary
   • Docgen stretch (see section below for details)

Docgen stretch

When #107 merges, we will effectively have a single source of authority for API usage. This paves the way for using an automated tool to generate documentation from code, e.g. extracting JSDoc blocks into neat pages. This would let us semi-automate the Glossary and Declaration docs so that they match the type definitions exactly.

Ordering

The order of the steps outlined in Overview is merely a suggestion. Furthermore, the Walkthrough itself should be continuously updated as various pages are merged, rewritten, and reorganized.

Feedback

None of this is set in stone; comments are always welcome.

[benbayard]

I don't think 3 or 4 are necessary. With #110 I think (3) isn't too necessary. I think (5) is super important!

Overall great work I would do 5 first and follow that up with (2) (6) and (7)