Writing Documentation

Writing documentation using markdown is simple and effective, but it's not always easy to see the result of what you write while you are writing it. Sensedia Docs provides a VSCode extension that allows you to visualize your markdown files as you write them.

📋 Table of Contents

1. Introduction
2. Using the VSCode Extension
3. Document structure
4. Document hierarchy
5. Conclusion
6. FAQ

Introduction

Writing documentation is a crucial part of the development process. It helps users understand your product and its features, and it can also serve as a reference for future development. In this section, we will discuss some best practices for writing effective documentation using Sensedia Docs.

Using the VSCode Extension

Sensedia Docs provides a VSCode extension that allows you to visualize your markdown files as you write them. This extension provides a live preview of your markdown files, so you can see how your documentation will look without having to publish it first.

Steps to Use the VSCode Extension

Document Structure

When writing documentation, it's important to follow a consistent structure to prevent errors when rendering the markdown, here is a basic structure you can follow:

Explanation of the Structure

• Front Matter: The section at the top of the document enclosed in ---
  • title: The title of your document.
  • description: A brief description of the document.
  • keywords: Keywords related to the document for search optimization.
  • parent: The parent document or section this document belongs to.
  • icon: Path to an icon representing the document. Required for product categories or products principal document.
  • order: The order in which this document should appear in the navigation.
  • swagger: Optional, used to include Swagger documentation.
• Content: The main body of your document, written in markdown syntax.

Example Document

Document Hierarchy

Sensedia Docs allows you to create a hierarchy of documents by using the parent field in the front matter. This helps organize your documentation into sections and subsections, making it easier for users to navigate.

Example of Document Hierarchy

In the context of Sensedia Docs, the last document in the hierarchy is the sensedia-docs, which is the main document that contains all the other documents. It serves as the root of your documentation structure. Do not forget to set the parent field to sensedia-docs in your main document.

Benefits of Document Hierarchy

• Organization: Helps keep related documents together.
• Navigation: Users can easily navigate through sections and subsections.
• Clarity: Provides a clear structure for your documentation.

Conclusion

The Sensedia Docs VSCode extension streamlines the documentation process by providing instant feedback and live previews, making it easier to create clear and visually appealing content. Leveraging Sensedia Docs markdown components further enhances the user experience, allowing you to build interactive and well-structured documentation that is both informative and engaging.

FAQ