[Proposal] Implementing a Style Guide for Logseq docs

Feedback
1

Hello Logseq Community,

As Logseq continues to grow in popularity, it’s essential to ensure that the documentation remains consistent, clear, and easily understood by users of various backgrounds and expertise levels. With that in mind, I’d like to propose the creation of a comprehensive style guide for writing Logseq documentation. A style guide will also set the expectations and requirements for community contributions.

Objective

This style guide’s primary objective is to establish guidelines and best practices for creating and maintaining high-quality documentation for Logseq. By implementing a style guide, we aim to achieve the following:

  1. Consistency: Maintain a uniform writing style, tone, and formatting across all Logseq documentation to provide a cohesive experience for users.
  2. Clarity: Ensure the documentation is clear, concise, and easy to understand, minimizing potential confusion or misunderstandings.
  3. Accessibility: Make the documentation accessible to users with varying levels of technical expertise, from beginners to advanced users.
  4. Ease of Maintenance: Streamline the process of updating and maintaining documentation by providing a clear set of guidelines for contributors to follow.

Key Components

The proposed style guide would cover the following key components:

  1. Writing Style and Tone: Guidelines for maintaining a consistent writing style and tone, focusing on clarity, simplicity, and user-friendliness.
  2. Formatting and Structure: Recommendations for organizing and structuring documentation, including headings, tables, blockquotes, emphasis, images, links, lists, and code blocks.
  3. Terminology and naming conventions: A glossary of terms and their preferred usage, ensuring that the documentation uses consistent language to describe Logseq features and functionality.
  4. Accessibility: Recommendations for ensuring the documentation is accessible to users with disabilities, including using appropriate semantic markup and clear, descriptive alt text for images.

Implementation Plan

To successfully implement the style guide, I propose the following steps:

  1. Research: Review existing documentation and identify areas of improvement or inconsistencies.
  2. Drafting: Develop a comprehensive style guide draft incorporating feedback from the Logseq team and community members.
  3. Review and Feedback: Share the draft style guide with the Logseq community for review and feedback, incorporating suggestions to improve the guide.
  4. Finalization: Finalize the style guide based on feedback and make it available to all contributors and team members.
  5. Documentation Review: Review and update existing Logseq documentation to align with the new style guide.
  6. Continuous Improvement: Regularly review and update the style guide as needed to accommodate changes in Logseq features or best practices in technical writing.

By implementing this style guide, I believe that the Logseq documentation will become more consistent, clear, and accessible to users, ultimately enhancing the overall user experience. I am eager to receive feedback and suggestions from the Logseq community to ensure that this proposal meets the needs of both the Logseq team and its users.

Thank you for considering this proposal. I look forward to collaborating with you all to improve the quality and consistency of Logseq documentation.

footer
Regards,

Bader <at> unsigned.sh

2

For everyone interested, the team said the one at https://docs.logseq.com is the technical documentation and they are working on a handbook directly in the app that should be enough for most users.

Also, everyone can contribute with threads in the Documentation category of this forum and Ramses said that eventually the most useful content could be used in the handbook.

3

The documentation available at docs.logseq.com serves as reference documentation rather than technical documentation. Technical documentation encompasses explanations of the software’s architecture, design patterns, code examples, tutorials, use cases, and best practices.

The primary objective of reference documentation is to deliver specific, detailed insights about the components and functionalities of a software product.
In the near future, a handbook containing ‘how-to guides’ will be introduced to assist users further.

That being said, this is not on topic. A style guide must be established for both the handbook and the reference documentation.

4

I reported exactly what Ramses said, including the term “technical”.

This is on topic as it makes other people aware that the documentation at docs.logseq.com will be joined by a less technical one that will be available directly in the app. This is what the team is planning to help users.

And it’s important to stress that people can help by writing in the Documentation category of this forum and that content can eventually end up in the handbook. At the moment there are posts only by Ramses and other two users, so better to remind it when there is chance.

1 Like