41 Standard Feature Documentation

[dendron-bot]

Goals

• NOTE: this note is exported from dendron. It is best viewed inside of the Dendron Community Workspace. See here on setup instructions

This is a proposal to introduce a standard way to document features in Dendron while minimizing duplicate content

Context

The past discussion about the dendron site is documented in [[Dendron Site Reorganization|dendron://dendron.community/discussion.2021.dendron-site-reorg]]

This proposal talks specifically about [[Feature Anatomy|dendron://dendron.community/discussion.2021.dendron-site-reorg#feature-anatomy]]

If you look at the sections of a feature, many of the sections (eg. [[CLI|dendron://dendron.dendron-site/templates.topic#cli]], [[Commands|dendron://dendron.dendron-site/templates.topic#commands]], etc) overlap with children of [[Reference|dendron://dendron.community/discussion.2021.dendron-site-reorg#reference]]

Proposal

When adding details to reference documentation under CLI, Configuration, the main text should come from dendron.topic.{feature}. The corresponding entries should be added as a note ref to their respective reference section. The way the reference documentation can be layed out as follows

• proposed layout for [[Command|dendron://dendron.dendron-site/dendron.ref.commands]] reference

<!-- Primary grouping by area, in same order as introduced in [[User Guide|dendron://dendron.community/discussion.2021.dendron-site-reorg#user-guide]] -->
## Editing

...

## Retrieval

...

## Refactoring
<!-- inside the respective areas, features are laid out alphabetically -->

<!-- 
Note the format: the header is a wikilink to the source documentation. this has multiple benefits:
- if we change the source header text or link, this will update
- if we delete the source header, this link can be found using `finddBrokenLinks` doctor command
- this still resolves to a clean url, both inside dendron as a URL: [[Rename Note|dendron://private/task.2022.01.26.on-structuring-dendron-docs.rfc#rename-note]]
- since this is an actual header, it shows up in the outline view inside vscode as well as in the TOC of the published site
-->
### [[Rename Note|dendron://dendron.dendron-site/dendron.topic.refactoring#rename-note]]

<!-- 
This is a wiki link that shows the content of the section
-->
![[dendron://dendron.dendron-site/dendron.topic.refactoring#rename-note,1:#*]]

Essentially, this is proposing that dendron.topic.{feature} is the main source of truth for a feature and reference.* documentation is generated as note references from topic notes.
This will help keep our docs DRY (don't repeat yourself) and make sure content is up to date.

Future Work

Currently, the process of generating references is quite manual. There are a few future features that should make this easier:

• When we ship [[22 Queries|dendron://dendron.docs/rfc.22-queries]], we should be able to vastly simplify this process with something like the below

  ## Refactoring
  <!-- Get all topics that are taged with `area.refactoring` and the child of dendron.topic. Extract `Commands` header from it -->
  ?[[ and (to tags area.refactoring) (children dendron.topic) ]]#Commands

[hikchoi]

This might be slightly tangential since the dicussion is mainly about organization, but I would like to also kick off some ideas on setting standards for the actual content we write.

Since everyone who works on a feature also works on the documentation, and everyone's writing style is different, I think it's important to have tools / guidelines that will let you check if the tone and vocabulary we use is consistent. Some formatting / linting of markdown would also benefit us when maintaining a readable document. (vscode extension pack for suggesting formatting tools for doc writing? I can imagine this would be great for onboarding people to our team + the community workspace)

I can recall that @ScriptAutomate has been using a tool to spellcheck stuff in dendron-site in the CI, and I've also seen some tools that uses unified to go through text and give you insights:

• https://alexjs.com/
• https://wooorm.com/readability/

These could be the first guardrail for us, then we could have some general writing guides about how we want our documents to be written similar to how we have development best practices in dev.process.

[SR--]

Yes, even the more popular ones like Grammarly are often silly or confused and are only meaningful as a provocation to rethink + a manual rewrite. These tools would definitely prevent Marcel Proust from ever publishing anything. They can still be useful.

[hikchoi]

I see. Would still be a good supplementary tool to have with us that will give us enough guidance in the process. Just not as a strict check

[SR--]

One consideration is that for writing the tool should be checking preview text but for code and other cases it might be the text in the editor. Same for the statistics requested here: #1887

[kevinslin]

hey @hikchoi - i think this is a worthwile discussion to have. can we create a separate thread about docs tooling?

[ScriptAutomate]

For everyone in this chain, since this is a bit off-topic compared to note templates for feature docs:

• Ideas for docs CLI / CI toolchain automation and extensions #2397

[ScriptAutomate]

I like the idea of having the source of truth exist within the feature documentation itself, and then for reference documentation to be large lists of note refs pulled from designated sections of the feature documentation (like ## Commands), as mentioned. This would require auditing of the documentation, and migrating content to different notes, in order to make sure we are adhering to the standard.

### [[Rename Note|dendron://dendron.dendron-site/dendron.topic.refactoring#rename-note]]

<!-- 
This is a wiki link that shows the content of the section
-->
![[dendron://dendron.dendron-site/dendron.topic.refactoring#rename-note,1:#*]]

I like this format as it means that the Headers also won't go out of date after any refactoring occurs. Once things like findBrokenLinks are in place, by Dendron: Doctor, we'd also be able to catch any problems that come out of notes/headers being renamed/deleted/moved without the refactor commands, too (which will be helpful in ongoing maintenance of docs health).

I think this is a great way of showing off Dendron for docs as it shows a good standard approach to remixing content, DRY, etc. while being able to create TL;DR types of docs out of existing docs.

[benhsm]

Something I'm wondering about - is there a reason Topics is "Topics" and not just "Features"? Are there items under "Topics" that are not features? It might make the documentation more legible to rename it, since "Topics" is perhaps a little difficult to disambiguate from other general categories like "Concepts".

[kevinslin]

The reason we use topics -> its meant to capture a set of features
For example:

• topic.refactoring refers to all refactoring related features
• rename note is a specific feature of topic.refactorign

[ScriptAutomate]

I'll be working on mapping out the implementation, and what dendron.topic.* notes will need to be reviewed and updated based on this standard. I'll be adding the information into the dendron.community vault, including every note in a checklist.

[jpknwls]

I like this structure. I think that in general, a specific API tends to be part of a large activity group, as well as a part of certain workflows. Here, the wider/flatter tree is the activity groups (Topics) while the workflows (CLI, Configuration,...) tend to be deeper trees. Having them accessible in separate locations according to either a) activity or b) workflow seems to solve for the main modes of documentation lookup: a) I'm trying to do something specific, or b) I'm figuring out a larger process. Having a structure that allows the building of workflows as the product of a set oftopic.{feature}s makes a lot of sense to limit repetition.

One tangential amendment I would make would be to stylize the commands, such that they contrast against the other content. I'm not sure this problem extends beyond me, but as I look at the documentation, it's hard to parse what is a section heading, and what is a command. Perhaps this could involve making the commands quoted, colored green, or emphasized in other ways; or adding separators between commands.