For full text search please use the '?' prefix. e.g. ? Onboarding

Standard Documentation

Summary

This leaflet proposes some general guidelines for the Dendron public docs.

  • Goals:

    • make it umnabiguous where to add docs on features and capabilities
    • make it umnabiguous where to find docs on features and capabilities
    • identify gaps in tooling that will make refactoring into and applying the standard easier in future iterations

  • Non-goals:

    • every note be 100% the same: we are still iterating on this standard and it will likely change in the future. it is more important we have a standard that people can follow than an XML spec that accounts for every possible permutation of docs
  • NOTE: this note was exported from this note. If certain links don't resolve, check the original note on github
  • Github Discussion

Concepts

For the purposes of this discussion, howtos/reference/discussions/tutorials refer to the four types of documentation

Topic Branch

A topic branch is a feature in Dendron. It is represented using dendron.topic (Private) hierarchy

Details

There are two areas that this leaflet addresses.

  • the overall structure of the docs
  • the structure for features

Overall Structure of Docs

This leaflet proposes the following changes:

  • simplify user guide (less children)
  • simplify dendron.* hierarchy to be product related topics
    • make contribution its own top level hierarchy
  • rename "Guides" to "How tos"

Resulting hierarchhy:

  • dendron
    • dendron.quickstart (Getting Started)
    • dendron.user-guide (User Guide)
      • Basic
      • Edit
      • Retrieve and Navigate
      • Navigation

        • fold into Retrieve

      • Organize Structure

        • Rename to Structure (Organization and Format)

      • Refactoring

        • Fold into Structure (Organization and Format)

      • Sharing and Syncing
      • Transferring

        • Rename to Sharing and Syncing

      • Extending
    • dendron.principles

      • fold into dendron home page

    • FAQ

      • move under dendron.resource

    • dendron.contribute

      • move to contribute (becomes top level hierarchy)

    • dendron.guides

      • Rename to dendron.howtos (How)

    • dendron.concepts (Concepts)
    • dendron.ref (Reference)
    • dendron.res (Resources)
      • dendron.res.faq
      • dendron.res.troubleshooting
      • dendron.res.support
  • contribute

    • everything from dendron.contribute gets moved here

  • community
  • changelog
  • careers

Structure for Features

All features today are added in the form dendron.topic.{feature}[.{sub-feature}|{sub-component}]

Sections

These are headers for features and are directly inside dendron.topic.{feature}

templates.topic (Private) (NOTE: link on handbook won't resolve on website, url: https://github.com/dendronhq/dendron-site/blob/dev/vault/templates.topic.md#L9:L9)

Children

These are the children of features and are located in dendron.topic.{feature}.*

Topic (Private) (NOTE: link on handbook won't resolve on website. url: https://github.com/dendronhq/dendron-site/blob/dev/vault/dendron.contribute.documentation.tutorial.top-level-feature.md#L8:L8)

Structure for References

From References
Go to text ā†’

Summary

This covers the references section of Standard Documentation in more detail.

Concepts

Refs

For the purposes of this note, a ref is anything that fits under dendron.roebe comprehensivcef. Examples:

  • cli
  • config
  • commands
  • apis

Structure of References

  • there should be an individual note for each ref

  • refs should be children ot the corresponding topic branch topic

    • eg. [[dendron.topic.template.config]]

  • if a topic branch has subcomponents, then the ref should be the child of the closest matching subcomponent

  • the config that is the direct child of a topic branch should have the index of all configuration for subcompoents as well as the topic

    • eg. dendron.topic.sidebar.config

      ## Global
<!-- This affects the topic directly (eg. sidebar configuration -->

### Foo
![[dendron.topic.sidebar.config.foo]]

## Tree View
<!-- This is the config for the tree view subcomponent. Should be a note ref-->
![[dendron.topic.sidebar.tree-view.config]]

...

  • dendron.ref.config (Private) should contain the index of all configuration, grouped by topic 

    - ...
- [[dendron.topic.lookup.config]]
- [[dendron.topic.sidebar.config]]
- ...

Additional Thoughts

  • in an ideal world, we can define the ref in one place and programatically generate the configuration indexes elsewhere
    • in the above example, we would add a config once in dendron.topic.sidebar.tree-view.config.nav_order
    • dendron should be smart enough to then include it in dendron.topic.sidebar.config, dendron.topic.config, and dendron.ref.config as needed
    • because we don't have this today, we are manually adding it in
    • in the future, we should be able to embed these sections using 22 Queries (Private)

topic : Topic Branch

Lookup

Children
  1. References
  2. Topics
Backlinks