First launch confusion for new users - no information on what a graph is/how files are read from/written to

i see in the discord documentation channel there are new docs in the works so maybe this is already on the radar, but just in case it helps:

i suggested logseq to a friend but wasn’t around to provide them with guidance. i thought their experience might be helpful for improving how new users learn about logseq:

the initial warning:

image

was very confusing - the person in question did not have an understanding of what a graph is. the language also somewhat implies that once you open a local folder anything you have done before that point will then be saved, or at least that’s how this person came to understand it.

working from that assumption the user began following the initial tutorial, building out a fair amount of pages in the demo graph while learning about the program (4.5+ hours). they then got to the “Add a graph” section of the tutorial (still with no understanding of what a graph is) and followed the steps to open a local directory, thinking the demo graph would be saved into the directory.

something else somewhat related to understanding ‘graphs’ is confusion about how logseq reads and writes to files on disk. even after following the program for a while i only have a vague understanding about the relationship between the markdown files, the in process database/cache, and git integration.

it might seem like overly technical information for the everyday user but a simplied diagram or introduction might be useful so people can understand what exactly they are editing and when/how things are saved.

if all of this already exists and i missed it my apologies. hopefully this example will shed light on some things that are a hurdle for people who might be new or never get far enough to follow through with feedback.

(not sure if this is ux/ui but wasn’t sure where else to post it)

edit: regarding the second part of the above post, found logseq/CODEBASE_OVERVIEW.md at master · logseq/logseq · GitHub and https://docs.logseq.com/#/page/The%20Refactoring%20Of%20Logseq in the discord documentation channel - a bit more technical than what i was imagining but a good starting point…