Logseq is constantly evolving, and so is its documentation. To make Logseq easier to use for everyone, we use the forum to write and maintain the manual. Want to contribute to the documentation and make Logseq better? Keep reading.
- Why we use the forum to write the documentation
Guidelines to contribute to the documentation
2. How-to guides
3. Reference guides
- Contribute by creating a new wiki post
- Contribute by editing an existing wiki post
- Help improve these guidelines
As per the original collaboration proposal, writing and hosting the Logseq documentation on the forum has two advantages:
- Collaboration is easy as this forum ships with wiki functionality.
- Google and other search engines index forum posts.
In this post, you’ll see how to collaborate on the forum by creating new wiki posts and editing existing ones. But first, we’ll look at the different types of documentation and what you should keep in mind when writing them.
In the following guidelines, we distinguish between four types of documentation and what are the characteristics of each. These principles will help you stay within scope and leave out what doesn’t fit.
The four types of documentation are:
- how-to guides
- reference guides
Different types of documentation are needed for different use cases and user situations. Picking types of documentation gives you direction for writing the content. The type of documentation will tell you what, how, and where to publish the documentation.
Each piece of documentation should be of only one type of documentation and have a single goal. In the four sections below, we’ll look at the principles of good documentation per type. Please keep these in mind when writing any piece of content on this forum.
All quotes are taken from Divio’s excellent book The Documentation System. We highly recommend you read this 24-page book if you plan to contribute to the Logseq documentation regularly.
The definition of a tutorial:
Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it.
Keep these principles in mind when writing tutorials:
In the beginning, we only learn anything by doing - it’s how we learn to talk or walk.
In your software tutorial, your learner needs to do things. The different things they do while following your tutorial need to cover a wide range of tools and operations, from the simplest ones at the start to more complex ones.
It’s perfectly acceptable if your beginner’s first steps are hand-held baby steps. It’s also perfectly acceptable if what you get the beginner to do is not the way an experienced person would, or even if it’s not the ‘correct’ way - a tutorial for beginners is not the same thing as a manual for best practice.
The point of a tutorial is to get your learner started on their journey, not to get them to a final destination.
One of your jobs as a tutor is to inspire the beginner’s confidence: in the software, in the tutorial, in the tutor, and, of course, in their own ability to achieve what’s being asked of them.
Many things contribute to this. A friendly tone helps, as does consistent use of language and a logical progression through the material. But the most important thing is that what you ask the beginner to do must work. The learner needs to see that the actions you ask them to take have the effect you say they will have.
If the learner’s actions produce an error or unexpected results, your tutorial has failed - even if it’s not your fault. When your students are there with you, you can rescue them; if they’re reading your documentation on their own you can’t - so you have to prevent that from happening in advance. This is, without doubt, easier said than done.
Everything the learner does should accomplish something comprehensible, however small. If your student has to do strange and incomprehensible things for two pages before they even see a result, that’s much too long. The effect of every action should be visible and evident as soon as possible, and the connection to the action should be clear.
The conclusion of each section of a tutorial, or the tutorial as a whole, must be a meaningful accomplishment.
Your tutorial must be reliably repeatable. This is not easy to achieve: people will be coming to it with different operating systems, levels of experience, and tools. What’s more, any software or resources they use are quite likely to change in the meantime.
The tutorial has to work for all of them, every time.
Tutorials unfortunately need regular and detailed testing to make sure that they still work.
Tutorials need to be concrete, built around specific, particular actions and outcomes.
The temptation to introduce abstraction is huge; it is how most computing derives its power. But all learning proceeds from the particular and concrete to the general and abstract, and asking the learner to appreciate levels of abstraction before they have even had a chance to grasp the concrete is poor teaching.
Don’t explain anything the learner doesn’t need to know in order to complete the tutorial. Extended discussion is important - just not in a tutorial. In a tutorial, it is an obstruction and a distraction. Only the bare minimum is appropriate. Instead, link to explanations elsewhere in the documentation.
Your tutorial needs to be focused on the task at hand. Maybe the command you’re introducing has many other options, or maybe there are different ways to access a certain API. It doesn’t matter: right now, your learner does not need to know about those in order to make progress.
- Good tutorials make learners achieve something meaningful/useful.
- Tutorials should convert visitors into users. Bad (or not having) tutorials means that people are less likely to use your product long-term.
- Tutorials should prepare learners to benefit from the rest of the documentation.
- Tutorials should be meaningful and valuable to the learner; this will help them stay motivated so they keep learning. The people who keep learning will become (power) users.
- Tutorials should get people started. Tutorials don’t even have to show best practices, as long as it’s easy to get started and get results as a learner.
- Short feedback loops that show clear and useful results are crucial if you want people to complete tutorials.
- The steps in tutorials should work on all supported systems at all times.
- Avoid abstract concepts in your tutorials!
- Keep tutorials minimalist. So, no in-depth discussions and no irrelevant (“nice to know”) information.
The definition of a how-to guide:
How-to guides take the reader through the steps required to solve a real-world problem. They are recipes, directions to achieve a specific end — for example: how to create a web form, how to plot a three-dimensional data-set, how to enable LDAP authentication. They are wholly goal-oriented.
Keep these principles in mind when writing how-to guides:
How-to guides must contain a list of steps to follow in order (just like tutorials do). You don’t have to start at the very beginning, just at a reasonable starting point. How-to guides should be reliable, but they don’t need to have the cast-iron repeatability of a tutorial.
How-to guides must focus on achieving a practical goal. Anything else is a distraction. As in tutorials, detailed explanations are out of place here.
A how-to guide must address a specific question or problem: How do I …?
This is one way in which how-to guides are distinct from tutorials: when it comes to a how-to guide, the reader can be assumed to know what they should achieve but don’t yet know how - whereas in the tutorial, you are responsible for deciding what things the reader needs to know about.
A how-to guide should not explain things. It’s not the place for discussions of that kind; they will simply get in the way of the action. If explanations are important, link to them.
A how-to guide should allow for slightly different ways of doing the same thing. It needs just enough flexibility in it that the user can see how it will apply to slightly different examples from the one you describe or understand how to adapt it to a slightly different system or configuration from the one you’re assuming. Don’t be so specific that the guide is useless for anything except the exact purpose you have in mind.
Practical usability is more valuable than completeness. Tutorials need to be complete, end-to-end guides; how-to guides do not. They can start and end where it seems appropriate to you. They don’t need to mention everything that there is to mention either, just because it is related to the topic. A bloated how-to guide doesn’t help the user get speedily to their solution.
The title of a how-to document should tell the user exactly what it does. How to create a class-based view is a good title. Creating a class-based view or worse, Class-based views, are not.
- How-to guides are like recipes that step-by-step work towards a specific goal.
- Whereas tutorials are aimed at beginners, how-to guides assume knowledge and work towards a specific outcome. To not frustrate users, don’t teach basic knowledge in a how-to guide.
- The audience of how-to guides are people who are already aware of the problem but don’t know how to solve it yet.
- How-to guides should be atomic and shouldn’t be exhaustive.
The definition of a reference guide:
Reference guides are technical descriptions of the machinery and how to operate it. Reference guides have one job only: to describe. They are code-determined because ultimately that’s what they describe: key classes, functions, APIs, and so they should list things like functions, fields, attributes, and methods, and set out how to use them. Reference material is information-oriented.
Keep these principles in mind when writing reference guides:
Give reference documentation the same structure as the codebase, so that the user can navigate both the code and the documentation for it at the same time. This will also help the maintainers see where reference documentation is missing or needs to be updated.
In reference guides, structure, tone, and format must all be consistent - as consistent as those of an encyclopedia or dictionary.
The only job of technical reference is to describe, as clearly and completely as possible. Anything else (explanation, discussion, instruction, speculation, opinion) is not only a distraction but will make it harder to use and maintain. Provide examples to illustrate the description when appropriate.
Avoid the temptation to use reference material to instruct in how to achieve things, beyond the basic scope of using the software, and don’t allow explanations of concepts or discussions of topics to develop. Instead, link to how-to guides, explanation and introductory tutorials as appropriate.
These descriptions must be accurate and kept up-to-date. Any discrepancy between the machinery and your description of it will inevitably lead a user astray.
- Reference guides tell users what something can do and how not to do things. They contain facts and characteristics.
- Reference materials should be consistently structured.
The definition of an explanation in terms of documentation:
Explanation, or discussions, clarify and illuminate a particular topic. They broaden the documentation’s coverage of a topic. They are understanding-oriented.
Explanations can equally well be described as discussions; they are discursive in nature. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.
Keep these principles in mind when writing explanation contributions:
Explanations are the place for background and context - for example, Web forms and how they are handled in Django, or Search in django CMS.
They can also explain why things are so - design decisions, historical reasons, technical constraints.
Explanation can consider alternatives, or multiple different approaches to the same question. For example, in an article on Django deployment, it would be appropriate to consider and evaluate different web server options,
Discussions can even consider and weigh up contrary opinions - for example, whether test modules should be in a package directory, or not.
Explanation should do things that the other parts of the documentation do not. It’s not the place of an explanation to instruct the user on how to do something. Nor should it provide a technical description. These functions of documentation are already taken care of in other sections.
- Explanations go in-depth and discuss the intricacies and why things are as they are. Explanations are aimed at cultivating understanding in the reader.
Do you want to share some knowledge about Logseq but can’t find an existing article it fits in? Then you should create a new wiki post.
A wiki post is a special type of post that can be edited by any user on your forum.
To create a wiki post just select the wrench icon:
And then click the Make Wiki button:
If a post is already a wiki, instead of the Make Wiki button, the Remove Wiki button will appear.
In case you don’t see this option, your user level is still too low. The minimum level to create new wikis is 3. If you already want to contribute, make a normal post in the Documentation category and a moderator will turn it into a wiki post at a later stage.
But you don’t need to start from scratch if you want to contribute to the Logseq documentation. When you’re reading a wiki post in the #docs category that contains incomplete, outdated, or wrong information, simply hit the Edit button at the top or bottom of the post.
If you don’t see the edit icon, you don’t have the proper trust level yet. To increase your trust level you must read, like, and reply to other people’s posts first. After about a dozen interactions on the forum, you’ll automatically be promoted to trust level 1.
To guarantee consistency, this post can only be edited by moderators. But you can still help out to make these guidelines better!
If you see that something is missing or can be phrased better, highlight the text in question, hit the Reply button, and share your suggestion. If your edit is accepted, a community leader will add it to this post.