Getting Started Guide: Review, community feedback, and refresh

[ScriptAutomate]

It's time for a revamp! Dendron has been growing 🌱 at a rapid pace, and that means revisiting and refreshing the experience for new users. I'll be reviewing Dendron's Getting Started Guide, which will include updating the Getting Started/Tutorial clone that is bundled with the Dendron extension.

As I take notes, tidy up, and replace screenshots, I want to make sure I don't miss valuable feedback from fellow Dendronites. This can be about problems/errors in the Getting Started Guide, or jumping off points to particular notes that would have been great to know early on.

Let's get to it: what are things you wish you'd known when starting out?

[xaamx]

A detailed guide on how to set it up for mobile use would have been very helpful. Took me a while but I've finally set it up with Noteless + Syncthing

[ScriptAutomate]

This is an interesting problem, because there are a variety of approaches a person can take to managing their notes on mobile.

At the moment, we have:

• Blog Post: Best Mobile Note-Taking Apps for Markdown
• Wiki: Dendron / Guides / Cookbook - Mobile

Looks like we could combine pieces of this information into the sparse Mobile Workflow page, and use that hierarchy as a way for members from the community to contribute their mobile workflows? There are so many potential combinations and apps that it is difficult to have a detailed guide, outside of listing the available apps that users could look into using.

[ScriptAutomate]

I've now done some slight updates to these links, and used a note ref of the Mobile cookbook section to create a better Mobile Workflow page.

[simkimsia]

Can i recommend to keep this discussion as the canonical place to log all feedback fro newcomers? because this should be a discussion that's permanent if you want to keep growing.

[ScriptAutomate]

Hmmm I'm thinking of creating a Getting Started Guide: Review each quarter. This would help create checkpoints and ensure proper full reviews happen outside of general feedback in the discord, and have comments/discussion that is more timely in relation to each refresh/revisit. I'm thinking this instead of a long, ongoing permanent discussion that may include out-dated feedback and content.

I'm wondering if it should double as a "New User Feedback" in general, or if I should have a separate discussion each quarter for new users to jump in and provide feedback?

It's interesting as GitHub Discussions, GitHub Issues, and the #feedback channel in the Dendron Discord all provide avenues for real-time feedback, while GitHub Discussions seem to work well as prompts for feedback.

[simkimsia]

Keep just one place for index all the common use cases. I really like how digitalocean has a treasure trove of tutorials for how to install software X in operating system Y.

Dendron needs the same thing. The categories are:

1. how to do this thing
   e.g. how to setup a dendron workspace inside your software project (don't say how to setup native workspace... beginners obv will not search with that term in mind)
2. how to do this thing in this other software i am coming from but in dendron
   e.g. how do i automatically go to today's journal note like in obsidian? (most beginners to dendron are not beginners to note taking apps per se... often they have some issues with the original note taking apps but at the same time they are comfortable with table stakes features and shortcut keys and you should reduce the amt of time for them to get to the same level of proficiency they were in theprevious app)
3. useful templates (and keep them up to date pls)... recently some versions complain that data is a wrong entry for the template. and i didn't know how to correct. I simply deleted it not knowing why. have 1 canonical place for all the templates. stop changing the web address. then delete all the outdated places (github repos, dendron wikis, etc) where templates used to live in or make sure they redirect or make explicit they are now deprecated.
4. What is .. ?
   e.g. This helps beginners to answer common questions that they have when they start using dendron. For example when they see in the command paletter "move header" the common question is what is "move header"? what does it mean? What's a header? The current explainer on Move Header is not beginner friendly enough. Better if can simply show a gif or a video

Drop the amount of lingo unique to dendron... seedlings, environmentlists , seeds, vault, etc... or introduce them more gently.

This is a huge pain point for me and very annoying.

[ScriptAutomate]

Some approaches to these are mentioned in @kevinslin 's comment here, along with my response to his suggestions.

The great thing about Dendron is that you can remix or easily internally link to other content, so I can see a jumping off point being a "Choose Your Own Adventure" approach ("How do I do...?" or "How do I do...when coming from....?") on a dedicated page of some kind that is also linked to from the Getting Started tutorial. Though, this would be like a FAQ, so maybe this could be part of revisiting the Dendron FAQ itself, or a page that acts as an extension to the FAQ?

When it comes to the What is...? about commands, I can see that commands like Move Header should be:

• In Commands, either directly or by way of note ref, since it looks like Move Header is in the Refactoring documentation but not referenced on the commands page at the moment. Then Commands can be a landing page for looking up the meaning of commands they see within the command palette.
• When it comes to the explainers: Good point on the Move Header command explanation, and how it could be better explained. I think in cases like this feedback, they would work well as dendron-site issue feedback so we can improve as we go. In the meantime, I'll be working to review and understand features/updates to the docs at release time when updates occur in the docs/changelog and using more detail when it looks needed.

In my PR for an initial update to the Getting Started guide, I'll be reviewing when new terms are introduced and defined (or needing gentler definition) within the tutorial.

I'll be linking my initial PR of first wave changes to this discussion, and will tag individuals involved in the discussion so far. Thanks for your feedback so far!

[kevinslin]

General recommendations

all videos/screenshots should be in note references

- this way we can always point to the same reference but update the underlying assets as needed
- create a asset hiearchy (eg. asset.*)

Bad

Check out the preview
![...](...)

Good

Check out the preview
![[dendron://dendron.dendron-site/asset.preview]]

Content

Default Jump Off Point

• this groups by difficulty and functional area
  • trail = easy, wilderness = hard
• #todo are notes for topiocs that we still need to format

## Trail
- Basics
    - [x] Finish the basics tutorial
- Retrieval
    - Search #todo
- Navigation
    - [[Find All References|dendron://dendron.dendron-site/dendron.topic.navigation#find-all-references]]
    - [[Go to Commands|dendron://dendron.dendron-site/dendron.topic.navigation#go-to]]
- Organizing
    - [[Tags|dendron://dendron.dendron-site/dendron.topic.tags]] 
    - [[Users|dendron://dendron.dendron-site/dendron.topic.users]]
    - [[Tasks|dendron://dendron.dendron-site/dendron.topic.tasks]]
    - Journal Notes #todo
    - Scratch Notes #todo
    - [[Hierarchies|dendron://dendron.dendron-site/dendron.topic.hierarchies]]
    - [[Schemas|dendron://dendron.dendron-site/dendron.topic.schema]]
- Sharing
    - [[Git|dendron://dendron.dendron-site/dendron.topic.git]]

## Forest
- Retrieval
    - [[Lookup Modifiers|dendron://dendron.dendron-site/dendron.topic.lookup.modifiers]]
- Editing
    - [[Frontmatter|dendron://dendron.dendron-site/dendron.topic.frontmatter]]
- Organizing
    - [[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
    - [[Publish|dendron://dendron.dendron-site/dendron.topic.publish]]
- Transfer
    - [[Pods|dendron://dendron.dendron-site/dendron.topic.pod]]

## Wilderness
- Sharing
    - [[Teams|dendron://dendron.dendron-site/dendron.topic.teams]]
- Extending
    - [[Hooks|dendron://dendron.dendron-site/dendron.topic.hooks]]

Jump off point depending on prior tools

• NOTE: this can be part of phase 2

• if you're coming from one of the following tools, this is how you can import your notes and start using Dendron

  • Obsidian
  • Roam
  • Notion

Jump off point on usecase

• NOTE: this can be part of phase 2

• meeting notes

• pkm

• work notes

• getting started

[ScriptAutomate]

• I really love the assets note ref approach! Will be implementing that
• When possible, should I be using the ![[dendron://dendron.dendron-site/asset.preview]] vs. ![[asset.preview]] format, due to what looks like better multi-vault scenario compatibility?
• I like the jump off point split into levels of difficulty. I think the Phase 2 jump off point items would be a great way to address the items that @simkimsia and @xaamx mention elsewhere in this discussion, more "Choose Your Own Adventure" based on what the person is wishing to achieve (use case, from prior tools, etc.).

[kevinslin]

* When possible, should I be using the `![[dendron://dendron.dendron-site/asset.preview]]` vs. `![[asset.preview]]` format, due to what looks like better multi-vault scenario compatibility?

Yes, use the full xvault link vs the naked one

[ScriptAutomate]

@simkimsia @xaamx I wanted to create this summarization with you two tagged (in addition to my direct replies within the discussion to the points you brought up). We just merged a large PR that has updated the Getting Started guide based on feedback in this discussion:

• Newly Updated Getting Started
  • GitHub PR

@simkimsia -> We have created several jumping off points in the Getting Started Conclusion, as a way for people to seek out other Dendron features. I'm thinking of adding this as a note ref in the Dendron FAQ, or maybe a dedicated page done in a "Learn how to..." listing of links, similar to the "How do I..." questions you were bringing up.

@xaamx -> I've now done some slight updates to these links, and used a note ref of the Mobile cookbook section to have a better Mobile Workflow page.

[SeriousBug]

The new tutorial looks amazing! A few thoughts I had looking through it:

1. In the User Interface, should we also mention that they can open the preview by clicking on the open preview button on the top right? We'll also have the option to open the preview by right clicking on any file in the File Explorer Pane or tab name once feat: open preview buttons for context menus #1906 is merged. I can also see this making the section too complicated though.
2. Nitpicking, but I would replace this example:

.
└── project1/
  ├── project1/designs/
  │   └── project1/designs/promotion.png
  ...

with

.
└── project1/
 ├── designs/
 │   └── promotion.png
 ...

3. When talking about lookup, should we also show off the tab autocomplete?
4. When discussing autocomplete, I think we should also mention how to bring back the autocomplete if the user dismisses it (Ctrl+Space by default I think?).
5. When talking about links, there's also autocomplete for headers. E.g. if you type [[the.note# Dendron should offer the headers in that note. I understand it might be hard to show off in the tutorial.
6. Just nitpicking, but I think everything in conclusion after the basics could be an unchecked box.
7. Should we also add a link to the RFCs page in the Wilderness section?

[Harshita-mindfire]

The tutorial looks great!
Adding a few thoughts for the same.

1. nitpick: Raised a PR for typos.
2. How does it sound to add a line about contextual UI in the below ACTION? Something like: Or click the lightbulb next to the header and select Rename Header

🌱 ACTION: Use the lookup to navigate to [[recipes.italian.desserts.gelato]]. Then:

Place the cursor in ## Ingredients, and run the command Dendron: Rename Note
Rename the note to ## Best Ingredients
Use the lookup to navigate to [[recipes.ingredients.shopping-list]]. You should see the wikilink there has updated from [[recipes.italian.desserts.gelato#ingredients]] to [[recipes.italian.desserts.gelato#best-ingredients]], ensuring links are updated!

Similarly for Rename Note, we can even use vscode built-in rename to rename a note and update all its references.

[nickolay-kondratyev]

Was thinking the same thing with activating Contextual UI when grabbing the header link.

If we can also word it that you dont have to click the lightbulb but can have the shortcut to activate contextual UI that would be helpful as well.

[ScriptAutomate]

This is so cool, I didn't even know about this 😅 so it feels like being shown an easter egg. I definitely want to get this in there, and in the [[Rename Note|dendron://dendron.dendron-site/dendron.topic.refactoring#rename-note]] docs section. Same with Copy Header Reference, because I've been doing it in a more annoying way without knowing the easy button.

[nickolay-kondratyev]

What also would be nice is to link to a page from Conclusion https://wiki.dendron.so/notes/TflY5kn29HOLpp1pWT9tP/ where we share some useful Extensions that go well with Dendron, for example Excel to Markdown table extension.

[ScriptAutomate]

That's a great idea. This makes me think it would be a good idea to include a link or two to other tools in the Dendron stack:

• VS Code docs
• Git docs
• GitHub docs
• etc.

[hikchoi]

Looks great! This reminds me that we should look into adding support for admonition blocks. These would have been very useful for highlighting the Action items.

[ScriptAutomate]

Agreed! I think a few others in the community would love it. Issue for reference in the discussion: #1287