Let's write some documentation together!

[Ramses]

Dear Logseqers,

For almost two years, we’ve been learning through trial and error as a community of Logseq developers and users. We mastered this tool by watching YouTube videos, reading blog posts, and hanging out in Discord. This works great to build a thriving community, but makes it hard for newcomers to adopt this tool.

To convert any first-time visitor to a user (and ultimately a contributor), they first need to learn how to use Logseq. And learning happens through good documentation; tutorials, how-to articles, reference guides, and in-depth explanations.

Unfortunately, our documentation is not that great at the moment. It was mostly written by engineers who prefer to write code over writing how-to articles. And while everyone can contribute to the documentation, you need skills like Git to be able to do so.

That’s why I want to propose that we write the Logseq documentation collaboratively and on this forum.

Let’s unpack this proposal a bit:

Let’s write the Logseq documentation collaboratively

Our engineers are busy building Logseq and our paid community team consists of just me. Yet, we have close to 20,000 active members in the community. And many of you know as much as we do about Logseq.

Luckily, you hang out in this forum and on Discord to help people one-on-one. Or maybe you even create content about how to use Logseq. But how much better would it be if you could easily add your knowledge to the official documentation?

That’s what I want to enable, and it also brings us to the second point.

Let’s write the Logseq documentation on this forum

If you’d want to contribute to docs.logseq.com today, you’d need to clone the GitHub repository, open it as a graph in Logseq, commit any changes you make, and push them back to GitHub. Then, you’d need to wait until a member of the Logseq team proofreads and accepts your changes. This can easily takes weeks. This is less than ideal, to say the least.

Lucky for us, our forum software (Discourse) ships with a wiki feature. That means that anyone with the right trust level (currently set to 3) can start a new wiki post. Anyone with trust level 1 can change existing wiki posts, updating them when they’re out of date or when a piece of information is missing. And vandals have no chance as all versions of all posts are saved, so reverting back to a previous version is a breeze.

There’s another advantage of writing and hosting the Logseq documentation on this forum: search engines. You see, docs.logseq.com is not indexed by Google and other search engines as it’s a Logseq graph. Currently, public graphs are not indexed. However, we want everyone to read the Logseq docs.

So, to make it easy to work on the documentation together and have search engines index our work, the best place to produce Logseq’s documentation is on this forum.

Want to help? Speak up!

There’s already a lot of content to help Logseq beginners and advancing users alike, but it’s scattered around the web. The first step is to bring over as much written and video content as possible to these forums.

I’ll set an example by transferring over all the articles from docs.logseq.com to the #docs category of this forum. This will take some weeks, but you can start contributing as soon as you appear a new wiki post. For example, by rewriting incorrect or unclear explanations. Or you can help out by starting a discussion about the piece of documentation by commenting on it (instead of directly editing the wiki entry).

If you’re a Logseq content creator and want to help out, please contribute your content. Many tutorials and how-to articles can easily be turned into documentation. If you have the right trust level, you can get started by posting your content as a wiki post in #docs. If you’re unsure if a piece of content would be a good fit, reply to this post with a link to your content.

If you want to help out but don’t know where to start, reply here. Mention anything Logseq related that you already have experience with (e.g. queries, workflows, plugins, CSS, etc.), and I can suggest a piece of content that needs work. I’m more than happy to work as an editor alongside anyone in the community, so send me a DM if you want me to proofread something you’ve written.

If you have comments on this proposal, I also want to hear from you. Please drop a reply

[Smithy]

Love the idea.

Writing from the point of view of a newbie, this is how I see it:

• We all have our own fields of knowledge we want to manage, everyone will have their individual interests and needs.
• Then there’s the data entry, creating the interconnectedness of the myriad of ideas.
• Finally, there’s the reflection and browsing, the flow, and retrieval, as necessary.

Data entry happens, as Ramses advises, mainly in the Daily Journal (mainly for newbies, or everyone?). From there, there are the various tools to connect, structure, organise, oversee (a big step will be to gain mastery of all that, like an orchestral conductor). This is where I’m struggling, to understand the practical application of the more complex opportunities available.

How to get all that growing knowledge into a fluid functioning system. And then there is the interaction and retrieval to benefit from all that work. Get the middle section right (the interconnectedness and structure), and it should all flow nicely. That’s what I’m looking forward to, and the documentation will help nicely!

I look forward to engaging

[rengen]

That’s a brilliant suggestion. I’ve just recently stepped into the Logseq world and I am not a power user yet, though I am happy to contribute if there’s anything I can help with!

[danzu]

What you are hinting at is a list of curated workflows. We have some in the forum, that should be moved into the documentation section.

[Ramses]

That’s a great idea. If they match the standard (How to contribute to Logseq’s documentation ), I’ll move them to this section.

But it’s not just about curated workflows. In fact, there are four levels of documentation is you ask me: tutorials, how-to guides, references guides, and in-depth explanations (background info). Again, see: How to contribute to Logseq’s documentation

[Martin_Sauter]

I absolutely see the need for proper documentation. However, I am not convinced that a forum is the ideal type of software/platform to create such a documentation, since it is just of collection of posts with no structure to guide a reader. Tools like Confluence, Slite, GitBook or Read The Docs are made for documentation, while a forum is made for communication.

[Smithy]

Hi Logseqers, I just posted in the Feedback section here, after discovering that Logseq can massively increase the file size of images, and came across documentation about importing images into Logseq, that I couldn’t even understand, reinforcing the need, I would say, to improve readability of the docs.

@Ramses

But it’s not just about curated workflows. In fact, there are four levels of documentation is you ask me: tutorials, how-to guides, references guides, and in-depth explanations (background info).

Absolutely @Ramses, but I only stumbled across the very useful hub.logseq page by chance, after using Logseq for some time (I read about it in your newsletter I think). And then there’s blog.logseq, and of course your newsletter. So please, can we also have information where to find the information.

@Martin_Sauter

Tools like Confluence, Slite, GitBook or Read The Docs are made for documentation, while a forum is made for communication.

Hi Martin @Martin_Sauter I never heard of those, welcome and thanks for mentioning them.

[Joe_Smoe]

I whole heartedly agree with this. I have managed Confluence at work to maintain and version control documentation for my department. I have also spent some extensive time testing different wiki’s and methods for documentation. While Confluence is probably out of the question here, I see a lot of good stuff in GitBooks.

Logseq needs well structured Documentation that covers the concepts, how to use those concepts, and features of the program. This should be done in a tool that’s designed to provide structured and clear guidance. Forums are not a means of that, since you can end up with endless conversations between user’s (much like what we are doing here) who all pitch in with their own opinions on a subject and could lead new users to confusion.

Once a user master’s the concepts and features, they’ll be ready to jump into the forum or discord to start discussing work-flows or use-case examples without feeling lost. This should lead to better promotion of introducing new user’s into this new arena without scaring them off.

GitBook’s own help page is a great example to show the effectiveness of well structured Documentation = Start exploring - GitBook Documentation

Let’s take the section from GitBook’s documentation talking about the concepts of Spaces. It covers “What is it?”, "How do I use it?, "Can I customize it?, etc etc…

Logseq should have similar documentation… for instance you can discuss the concept of “Page References”, and cover what they are, how to create page references, customizing the text displayed on a page ref, etc etc…

I do see that there’s already a https://hub.logseq.com page, but it’s lacking that structure, and kinda deep dives into use-cases, work-flows, and other things without first getting the user comfortable with concepts and features.

The getting started section only mentions 2 videos, but no actual documentation that goes along with it… and it’s all just thrown into a single page. I would suggest maybe structure it this way.

# Getting Started
{{ Button navigation to other sections that cover the various concepts }}

{{button to Graph page}}
high level overview about what graphs are

{{button to Page References page}}
high level overview about block references

## Graph
- What is a graph?
  - What makes up a graph?
  - How to create a graph?
  - Renaming an existing graph?
- How to customize your graph
  - What is the config.edn file?
  - How to modify your settings?
- Customizing the appearance of your graph
  - Editing the custom.css file

## Page References
- What are page references?
  - How to create a page reference?
  - Renaming a Page Reference
- Customizing your page references
  - How to display custom text in your page reference
  - Adding CSS styling to your page references

## Block References
- What is a block reference?
  - How do block references work?
  - How to perform a block lookup?

[doubL_HeliX]

I agree on the need for good docs as well. However, I believe strongly that a forum is not the best place for documentation, especially if you want to attract new users with a clean, clear explanation, instead of making them “hunt” for answers; I do think people want to be delivered both an official reference, as well as a tutorial, despite how useful forums are, especially in a conscientious, small community like this (on stackoverflow, you can get the wrong answer if you don’t read the comments to the accepted or most upvoted answer!) Maybe you could scour the forum for useful paragraphs to use in official documentation, or use the types of questions asked here to prioritize the official documents. But I do think they need to be separate.

EDIT: In the last few months, as a new user, I’ve literally come to love logseq, and I tell all my dev friends about it. Thinking about the future of the documentation actually kept me up at night a few days ago, because I know how much logseq has to offer people. As the entrypoint for new users, the documentation needs to be clear, and guide them through the steep learning curve, which is easy to forget about once you’ve been using logseq for several months, and have been, as in my case a) reading the whole official docs b) following the examples on hub.logseq.com, and c) watching tons of youtube videos to fill in the gaps and add to my understanding.

[Martin_Sauter]

You may have heard or read of the Unofficial Logseq Docs at https://unofficial-logseq-docs.gitbook.io already.

As I mentioned in an earlier post, that’s exactly the type of documentation that Logseq is laking at the moment. However, creating an «unofficial» documentation by an individual or small group is not the right way to go in my opinion: We should join forces in the Logseq community and create one single «official» documentation.

Since the approach of creating such a documentation within this forum (which I personally still consider a bad idea) did not get much traction, it’s about time to rethink the whole documentation question. It’s such a pity to have a gread app but a fragmented, incomplete and outdated documentation, and this will harm the adoption of Logseq.

[alex0]

docs.logseq.com is getting better, maybe there is need for a guide on how to contribute?

[Junyi_Du]

Kindly remind that we just setup a project board for documents Logseq - Develop Together 💪 · GitHub

[Martin_Sauter]

I wasn’t even aware that the community can contribute to this documentation. If that’s the case, then a guide would be certainly needed.

However, creating the documentation for Logseq in Logseq has upsides and downsides. While I see the point of eating your own dog food, Logseq is not particularly suited for working in a team, and it is also laking a hierarchical navigation structure which I think is essential for a documentations.

[sri]

The two links near the bottom of How to get started with Logseq's Journals page seem to be broken.

Screenshot:

[sri]

Apparently :date-formatter in https://docs.logseq.com/#/page/63ceaa33-9fa4-40b2-9d5b-a69f3b7b6d6c is deprecated. It should be :journal/page-title-format.

Discord discussion.