Dendron Site Reorganization

[dendron-bot]

Summary

This is divided into two parts.

1. Site Organization is how the new site should be organized
2. Other Things contains other proposals and feature proposals to make the site easier to use

• NOTE: this discussion is available in [[Dendron Site Reorganization|dendron://private/proj.2021-11-dendron-site-reorg.v1]] inside the Dendron team workspace.

Tags

• #later: means this will be done at a later phase and won't be part of the initial migration

Site Organization

Top Level Hiearchy

- Dendron
    - Getting Started (dendron.tutorial)
        - ...
    - User Guide (dendron.user-guide)
        - Basics 
        - Editing Notes
        - Finding Notes
        - Organizing Notes
        - Sharing Notes
        - Transferring Notes
        - Extending Notes
    - FAQ (dendron.faq)
        - Editing
        - Retrieving
        - Organizing
        - Sharing
        - Transferring
        - Extending
        - Alternatives
    - Guides (dendron.guides)
        - Cookbook
        - Troubleshooting
        - Workflows ^4IoiAStDDgq5
    - Concepts
    - Contribute
    - Careers
    - Reference ^ARvwCTHH57rH
        - CLI: contains all CLI commands
        - Configuration: all configuration
        - Commands: all commands
        - Features: all features (topics)
        - Dendron Maturity Levels (dendron.ref.maturity)
        - Telemetry: Our telemetry notice
- Changelog
    - v0.6x
    - v0.x
    - ...
- Community 
    - ...
- Tags

Details

• Getting Started: linear tutorial
• User Guide: all current topics arranged by area. All areas are actions that are related to notes
  • Basics: fundamental core features of Dendron
  • Editing
  • Retrieving
  • Organizing
  • Sharing
  • Transferring: move notes to other places (pods)
  • Extending: extending Dendron (note type system, custom pods, hooks)
• FAQ: frequently asked questions, made up of note references pointing to existing features
• Guides: walkthroughs
• Concepts: definition of terms, made up of note references pointing to existing features
• Contribute: how to contribute to Dendron
• Careers: jobs page
• Reference: an appendix to lookup specific information

User Guide

Basics

- [[Lookup|dendron://dendron.dendron-site/dendron.topic.lookup]]
- [[Hierarchies|dendron://dendron.dendron-site/dendron.topic.hierarchies]]
- [[Markdown|dendron://dendron.dendron-site/dendron.topic.markdown]]
- [[Images|dendron://dendron.dendron-site/dendron.topic.images]]
- [[Links|dendron://dendron.dendron-site/dendron.topic.links]]
- [[References|dendron://dendron.dendron-site/dendron.topic.references]]
- [[Templates|dendron://dendron.dendron-site/dendron.topic.templates]]
- Journals (todo: split out into own section)
- [[Workbench|dendron://dendron.dendron-site/dendron.topic.workbench]]
- [[Graph View|dendron://dendron.dendron-site/dendron.topic.graph-view]]

Editing Notes

• [[Frontmatter|dendron://dendron.dendron-site/dendron.topic.frontmatter]]
• [[Note References|dendron://dendron.dendron-site/dendron.topic.references]]
• Math and Diagrams

Finding Notes

• [[Lookup Modifiers|dendron://dendron.dendron-site/dendron.topic.lookup.modifiers]]
• [[Lookup Keybindings|dendron://dendron.dendron-site/dendron.topic.lookup.keybindings]]
• Search? (don't currently have a note on this)

Organizing Notes

• [[Schemas|dendron://dendron.dendron-site/dendron.topic.schema]]
• Builtin Note Types(todo: create)
  • [[Tags|dendron://dendron.dendron-site/dendron.topic.tags]]
  • [[Users|dendron://dendron.dendron-site/dendron.topic.users]]
  • [[Tasks|dendron://dendron.dendron-site/dendron.topic.tasks]]
  • [[Special Notes|dendron://dendron.dendron-site/dendron.topic.special-notes]]
• [[Vaults|dendron://dendron.dendron-site/dendron.topic.vaults]]
• [[Workspace|dendron://dendron.dendron-site/dendron.topic.workspace]]
• [[Multi Vault|dendron://dendron.dendron-site/dendron.topic.multi-vault]]

Sharing Notes

• [[Git|dendron://dendron.dendron-site/dendron.topic.git]]
• [[Publish|dendron://dendron.dendron-site/dendron.topic.publish]]
• [[Teams|dendron://dendron.dendron-site/dendron.topic.teams]]

Transferring Notes

• [[Pods|dendron://dendron.dendron-site/dendron.topic.pod]]

Extending Notes

• Note Type System (todo)
• [[Hooks|dendron://dendron.dendron-site/dendron.topic.hooks]]
• Custom Pods (todo)

Feature Anatomy

A feature is represented as dendron.topic.*.
Every topic is a feature with the following template

## Summary
<!-- 3 sentence description of the feature -->

## Details
<!-- In depth explanation of feature -->

## Concepts
<!-- Concepts that relate particular topic-->

## Examples
<!-- showcase sample use cases -->

## Commands
<!-- VSCode specific commands if applicable -->

## CLI
<!-- cli specific commands if applicable -->

## Config
<!-- configuration if applicable -->

## FAQ
<!-- Commonly asked questions -->

## Cookbook
<!-- Commonly used commands -->

## Troubleshooting
<!-- Common errors -->

If a feature has subfeatures, they should be a child of the topic and show up under children.

FAQ

Every feature has its own FAQ in its own hierarchy. The FAQ note has note references into each topic. These note references are grouped in the same way as the User Guide

In adition, it also has some specific questions that are not feature related (eg. Dendron Alternatives)

Guides

Guides on how to do specific things

• Cookbook: compiled from note reference of all features ¹
• Troubleshooting: compiled from note reference of all features
• Workflows: manually written tutorials on common workflows (eg. zettelkasten, bullet journal, etc)
  • move notes from [[dendron.case-studies]]

Concepts

Compiled from note reference of all feature

Contribute

Same as today. Group by [[mark suggestion|dendron://private/user.hikchoi.scratch.2021.10.30.site-reorg#dendroncontribute]]

Careers

This is the dendron.jobs page

Reference

The reference section is an appendix of everything. It is a horizontal slice across all features.

• CLI: compiled from note reference of all features
• Configuration: compiled from note reference of all features
• Commands: compiled from note reference of all features
• Features: link to all features
• Dendron Maturity Levels (dendron.ref.maturity)
• Telemetry: Our telemetry notice

Changelog

Same as current

Community

Same as current

Tags

Same as current

---

Other Things

More useful Schemas

#later

• See [[Jonathan schema comment|dendron://private/scratch.2021.10.27.212301.jonathan-dendron-site-remap#^GVdwkabWPsUf]]
• We should make schemas more useful (eg. click on a schema to get an overview of what it covers) in published pages (or remove them if they are not useful)

Admonitions

#later

• we should use the following to indicate special information

• NOTE: an important detail that should be taken into account

• TIP: something that will make

• WARNING: a potentially destructive action

Content Migration

The following notes should be migrated to a different domain

• move to docs.dendron.so
  • pkg.*
  • dendron.rfc.*

Landing Page additions

• merge notes from [[dendron.features]] here
• move [[dendron.testimonials]] to landing page

Tasks

• plug onboarding and open pkm at the end of tutorial

• remove

  • dendron.blog
  • templates
  • dendron.cheatsheet
  • dendron.discussion

• rename

  • dendron.topic.references -> dendron.topic.note-reference
  • dendron.release -> dendron.changelog

• move

  • dendron.topic.math >> dendron.topic.math-and-diagram
  • dendron.topic.markdown#mermaid >> dendron.topic.math-and-diagram

Footnotes

1. this means taking a note reference of the same section from each feature of Dendron if it exist. you can see the sections within each feature in [[Feature Anatomy|dendron://private/proj.2021-11-dendron-site-reorg.v1#feature-anatomy]]. Unless otherwise stated, the note references will be grouped by action (see user guide). Not all features will have a note reference for each section. ↩

[hrmnjt]

I think having a dendron.rfc.* in the docs gives an idea to users for upcoming features. Something I have always referred to in other open source projects. Examples:

• https://cwiki.apache.org/confluence/display/kafka/kafka+improvement+proposals
• https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvements+Proposals

[simkimsia]

Cannot find a subscribe button so I replied here to follow

[kevinslin]

I think having a dendron.rfc.* in the docs gives an idea to users for upcoming features. Something I have always referred to in other open source projects. Examples:

* https://cwiki.apache.org/confluence/display/kafka/kafka+improvement+proposals

* https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvements+Proposals

would you expect to see the rfc in wiki.dendron.so? our proposal here is to move it to docs.dendron.so which is also where the developer docs will live

[SR--]

Please consider adding complete descriptions of both typical and distinct use cases (step-by-step recipes). Videos would be best as the they can catch the detail that seems obvious to the developers and also can preclude the provision of potentially unfunctional instructions. For example:

1. Publishing on the GitHub using GitHub actions from start to finish (include branching cases, updating, updating in a team, private vs public repos, etc)

Consider labeling them with the version number.

[andrey-jef]

when writing step-by-step guides, hope we can consider a solution like scribe

[simkimsia]

consider adding complete descriptions of both typical and distinct use cases (step-by-step recipes).

Strong agree abt this.

Analogizing this with OOP

=> typical is like class in OOP
=> and distinct is instance in OOP

both are helpful

[hikchoi]

Just leaving my thoughts on the Feature Anatomy template.

I personally think the sections that don't have actual content should explicitly say so

e.g. in dendron.topic.featureA, under ## CLI, even if featureA is not exposed by the CLI, it should still have something like "featureA is not supported by the CLI at this point of time". Since all topic.* will have the same anatomy, we could search for that specific section and know right away that it's not there yet. Otherwise, we will have to wonder if that's truly the case. The downside is that we will have a lot of placeholders in our doc.

[ScriptAutomate]

I like having placeholders of explicit non-support than the ambiguity of potential support. We could have a default note ref to include in templates that gives a generic statement ("This feature is currently not supported by the CLI."), too, because then the backlink page of the note ref would be like a listing of all features not currently supported in the CLI?

[kevinslin]

we can have a distinction between - this feature is not currently supported and support for this is not applicable (eg. table of contents for publishing is a feature but has no CLI support)

there will be features that introduce no concepts/cli/config. one worry is that having it there would needlessly clutter up the docs.
but there is something to be said for consistency.

[hikchoi]

I think for a hierarchy like topics where we strive to be thorough and encyclopedic we gain a lot from consistency and being explicit. We can choose to not reference the placeholders at places where clutter is a concern.

[nickolay-kondratyev]

In the feature anatomy template we currently jump straight into Details after the summary. Wondering whether it would make sense to have some sort of Basic Usage section before details, where the most basic usage of this feature would be placed if such usage exists (or in case of complex features it would just say [[#details]]). As example for note lookup we have a bunch of detailed usages but the basic usage of note look up could still exist as its own section of just doing the most basic possible lookups.

[ScriptAutomate]

I've created a follow-up issue on remaining site reorg steps: dendronhq/dendron-site#278

Tagging users in this discussion that may be interested:

• @SR--
• @simkimsia
• @hrmnjt
• @andrey-jef

[simkimsia]

Thanks for tagging me @ScriptAutomate

[hrmnjt]

Thanks for tagging. Will check the new discussion.