Standard Documentation Format

[kevinslin]

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

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 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}

Feature Template (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}.*

Top Level Feature (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

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.ref. Examples:

• cli
• config
• commands
• apis

Structure of References

• there should be an individual note for each ref

  • eg: nav_order

• 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

  • eg. nav_order

• 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 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

[^topic] : Topic Branch

[kevinslin]

Adding link to this PR refactoring the refactor docs with further comments on the standard doc format

dendronhq/dendron-site#540

[rlh1994]

Sorry in advance

I've been thinking about this quite a bit, and I'm still not sure I have my thoughts entirely clear so bare with me through this essay. I genuinely started this thinking I'd just write up a short bit about what I'd been thinking 🥲

tl;dr: regardless of where it is, define truths at a sensible atomic level (in whatever hierarchy you want, being atomic means refactoring is easy using dendron), and use these within a context to ensure consistency and up-to-dateness, but go too far and you end up with absurd (but also strict) scenarios and difficulty when you have to re-combine truths.

Setting the scene

I think for me it's not so much specifically about the hierarchy structure for me in either topic or ref, but about the atomicity of the content itself. This combines with the fact that breaking it down there is really two types of content we are talking about; one is the truths which might be everything from term definitions to code command usage or code examples to even images (in some scenarios). The other is then your opinions or context, having all your truths is of no use you can't provide context to them which might be showing how they fit together, providing things like analogies, anecdotes, or opinionated commentary around them (even if you might not realise it's an opinion at the time!). The line probably slightly blurs when you are building the tool itself, so I'll try and talk of some more general things and it can then be applied to dendron-specific things at the discretion of the dev team (i.e. you choose what is a truth you enforce vs an opinion/context). I think of context more like a tech blog post or tutorial, it's used to provide you with the truths.

Okay but how does it work

Okay so now we have those defined we can take it back to atomicity again, how far can we break something down to it's most singular level. This is relatively easy to follow for truths:

• Definitions/terms -> a singular term and definition
• All code commands -> A single code command
  • (-> arguments commands, I'll come back to this)
• Code Examples -> A single example (defined by the code but equally by what it is demonstrating)
• all images -> A single image (defined by what is of, not the unique image itself e.g. an image that shows a golden retriever dog, meaning you could swap this for another image of a golden retriever and anywhere it was used should still be valid).

I personally find it harder to follow this breaking down process for a context, because (okay partly by my literal definition of them) they don't have such an atomic nature - the same truth may appear multiple times, or the truth is mixed in with an opinion that makes it harder to truly split these (bringing it slightly back to dendron, the lowest level we can realistically split at is a header, but within a header there may be a mix of context and facts).

The other thing about contexts is that there is likely to be overlap between them - a workspace for example is a unique topic currently, but when talking about them as a context specifically for dendron, you may need to bring up how they relate to vscode, or how you offer commands relating to vaults (another stand alone context) to push/pull (version control context) on them. Now the context specific part of these may be unique to each area, but the truths you talk about should be the same i.e. how you define the term vault should be the same across all of them, and if you use a code snippet in multiple contexts it should always match.

By keeping your truths separate and referencing/embedding them in your context you ensure that you always have the same information regardless of what context it's used in, and that if you need to update it, you only need to do it in one place.

How should contexts reference truths?

It's important that the context only mentions the whole truth (or even a higher level above the atomic truth) and doesn't try to add context to a sub-part of it (which if you need to, the truth need to be split further to a more atomic level). Take the dog photo example again; narrative in the context might refer to the dog in the photo, or the golden retriever, but shouldn't mention the good boy chasing a squirrel, because the photo might change to a good girl fetching a ball. If the context needs to explicitly reference what the dog is doing, the fact should be split to contain that information i.e.

dog.golden_retriever ->
     dog.golden_retriever.chasing_squirrel
     dog.golden_retriever.fetching_ball

Let's just recap

So we define the idea of truths and contexts. Truths are split only as atomic as needed for the contexts they are used in, and provide very specific content, often following a standard structure based on the type of truth. Contexts bring together truths and provide narrative around them to help convey the truths to a user, they can reference either the level of or higher level of a fact (e.g. they may talk about all dogs but use an image (truth) of a specific one, or may talk about how to use an API generally but provide a specific example (truth)). If the context needs to reference something of the truth that is not part of the truth's unique definition, then the truth should be further split so that becomes part of it's unique definition.

Doing this ensures single source of truth updating, and allows for re-use of truths across multiple contexts, plus contexts can reference other contexts (but truths should not reference truths at the same or a higher level - they can reference lower levels to become a meta-truth).

Okay now let's take it too far

This section is more messy than even the rest, I don't really have it solved and it highlights the issues with this approach, more just me thinking aloud, sorry!

I mentioned above that you could split code commands in two different paths, one for the command itself, and the other for the arguments of commands. You could also go further and add flags. Let's use git here as an example. So you might have something like the following

• commands
  • push
  • pull
  • fetch
  • checkout
  • ...
• arguments
  • branch-name
  • remote
  • commit-hash
  • ...
• flags
  • v (verbose)
  • r (recursive)
  • m (message)
  • ...

Great, we can now use the same definition of the commit-hash argument across multiple commands and contexts and if we update that definition it will do it everywhere. But we hit a few problems:

1. What about if an argument or flag has different definitions or uses depending on the command? You could say they should be consistent within a program, but what about across git and dendron for example?
2. I said truths shouldn't reference other truths at the same or higher level, but in this case push has arguments and flags, as well as a definition, so how can we reconcile this?

We can solve problem 1 by just further atomising, however this might get messy if the same argument name or flag gets lot's of different uses (although that might be bad just in general and highlight an issue?):

• commands
  • push
  • pull
  • fetch
  • checkout
  • ...
• arguments
  • branch-name.default (used by majority and should be the default for any new cases)
  • branch-name.checkout (used just by checkout)
  • remote
  • commit-hash
  • ...
• flags
  • v (verbose)
  • r (recursive)
  • m (message)
  • ...

Problem number 2 I don't have a solution for, we could go deeper on a hierarchy but it feels like just doing it for the sake of it (or flip the previous approach but this then removes the ease of consolidating all uses of a term...):

• dendron
  • ...
• git
  • push (can now reference arguments and flags as they are a level lower)
  • pull
  • fetch
  • checkout
  • ...
• command_parts
  • arguments
    • branch-name.default (used by majority and should be the default for any new cases)
    • branch-name.checkout (used just by checkout)
    • remote
    • commit-hash
    • ...
  • flags
    • v.default (used by default for majority of commands, as git uses this for all there is no need for v.git.default)
    • v.deondron.default (used as the default for dendron, but differs to the majority)
    • v.dendron.doctor (used by dendron doctor, differs from the dendron default and the overall default)
    • r (recursive)
    • m (message)
    • ...

It might seem like an extreme example but if you want to ensure that you are consistent with argument names or flags, this would be one way to enforce/identify it, but it isn't very elegant... In general I don't have a solution to this problem.

So what does this actually look like?

I've been subconsciously treating truths to mean a reference i.e. ref, an context to be the existing topics but this doesn't really have to be the case, you just have to have some part of a hierarchy where you define atomic truths, and then these are embedded within some part of a hierarchy where you give the contexts.

Downside is if you go quite atomic with the truths if you either end up with a lot of nested embeds (e.g. you reference a command that references arguments), or you have to embed a lot of small things throughout.

annndd rest 💤

[kevinslin]

currently, the way ANTs are created as References. truths are grouped by sections. other notes can then reference the entire note, a section, or a particular part of the ANT.

lets take a look at an excerpt from Note CLI

• dendron.topic.notes.cli.md

  ## Commands
  
  ### lookup
  ![[dendron://dendron.dendron-site/dendron.topic.notes.cli.lookup#summary,1:#*]]
  
  ### move
  ...
  
  <!-- Output -->
  ## Commands
  
  ### lookup
  
  Query for notes in your workspace
  
  ### move
  
  ...

• limitations with using body text in notes as truth:

  • lake of granularity (sentence level is as specific as it will be)
  • lack of validation (eg. you want to specify the type of the argument, constrain to set of valid values)

truth via frontmatter

this involves adding all truths inside the frontmatter of a note. this overcomes some of the limitations of the previous approach.

• references can be granular and for a specific field (NOTE: currently not supported but discussed in rfc 47)
• references can be enforced via tools like json schema

this still has some limitations depending on how extensive your usecase is. to have global ANT, we should ideally store everything as string identifiers that can be localized using tools like gettext

truths and context

I personally find it harder to follow this breaking down process for a context, because (okay partly by my literal definition of them) they don't have such an atomic nature - the same truth may appear multiple times, or the truth is mixed in with an opinion that makes it harder to truly split these (bringing it slightly back to dendron, the lowest level we can realistically split at is a header, but within a header there may be a mix of context and facts).

see the truth via frontmatter section. if we adopt this approach, it will be much easier to be granular when re-using truth in context.

as for when and where to break down a note, i think its fine to start off using the Amoeba Workflow. once more people get involved and the scale of the operation gets bigger, then it makes sense to standardize with efforts like this one.

a next step after this standardization is to figure out what features we can add to Schemas to programatically enforce the standard

very granular truths

I mentioned above that you could split code commands in two different paths, one for the command itself, and the other for the arguments of commands. You could also go further and add flags. Let's use git here as an example. So you might have something like the following

for this example, i think it depends on context. if your options never overlap, then there's no problem just embedding options into notes and not splitting further. if your options do overlap, i find its usefult to create an escape hatch that has global properties (eg. common.git-options.branch-name) and embed that when needed. you can then append with alternatives (eg. common.git-options.branch-name.checkout)