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.
Index
- Why we use the forum to write the documentation
- Guidelines to contribute to the documentation
1. Tutorials
2. How-to guides
3. Reference guides
4. Explanations - Contribute by creating a new wiki post
- Contribute by editing an existing wiki post
- Help improve these guidelines
Why we use the forum to write the documentation
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.
Guidelines to contribute to the documentation
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:
- tutorials
- how-to guides
- reference guides
- explanations
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.
1. Tutorials
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:
1.1. Allow the user to learn by doing
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.
1.2. Get the user started
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.
1.3. Make sure that your tutorial works
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.
1.4. Ensure the user sees results immediately
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.
1.5. Make your tutorial repeatable
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.
1.6. Focus on concrete steps, not abstract concepts
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.
1.7. Provide the minimum necessary explanation
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.
1.8. Focus only on the steps the user needs to take
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.
In summary:
- 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.
2. How-to guides
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:
2.1. Provide a series of steps
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.
2.2. Focus on results
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.
2.3. Solve a particular problem
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.
2.4. Donât explain concepts
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.
2.5. Allow for some flexibility
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.
2.6. Leave things out
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.
2.7. Name guides well
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.
In summary:
- 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.
3. Reference guides
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:
3.1. Structure the documentation around the code
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.
3.2. Be consistent
In reference guides, structure, tone, and format must all be consistent - as consistent as those of an encyclopedia or dictionary.
3.3. Do nothing but describe
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.
3.4. Be accurate
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.
In summary:
- 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.
4. Explanations
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:
4.1. Provide context
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.
4.2. Discuss alternatives and opinions
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.
4.3. Donât instruct, or provide technical reference
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.
In summary:
- Explanations go in-depth and discuss the intricacies and why things are as they are. Explanations are aimed at cultivating understanding in the reader.
Contribute by creating a new wiki post
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.
Contribute by editing an existing wiki post
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.
Help improve these guidelines
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.
