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