Skip to main content

Contributing

Guidelines for contributing documentation

Bookstack Basics:

  • Documentation in Bookstack is organized into Books.
  • Each Book contains Pages which contain documentation.
  • Pages within a book can be grouped into Chapters.
  • Books which are related can be grouped into Shelves
  • Books can be placed on multiple shelves

Vector Bookstack Structure:

Adhere to the following structure when contributing documentation:

  • Shelf - Team
  • Book - Project
  • Chapter - Subproject or Topic Category
  • Page - Specific subject

For example:
Shelf → Book → Chapter → Page : AI Infra Team → Vec Inf Project → Getting Started → Slurm Basics

Additional Organizational Tips:

  • If a project is shared across multiple teams, then the book for that project can be placed on both of the shelves for each team.
  • Books are private by default.
    • Books should only be made public if they are intended to be shared with those who are not Vector proffessional staff and do not contain sensitive information.
    • If a book is made public, all the pages and chapters within that book are also made public. You can override this by explicitly editing the permissions of a page to make it private again.
    • Alternatively you can leave a book as private, and set specific pages within the book to be public
  • Team Shelves should be made public.
    • Making a shelf public does not make the books within that shelf public.

Formatting Tips

Editor

The default editor for this Bookstack wiki has been set to Markdown. If you prefer a more traditional WYSIWYG editor (What You See Is What You Get) similar to microsoft word then at then when editing a page select the "Editing Page" or "Draft Saved ..." button at the top center of the screen and select "Switch to WYSIWYG Editor".

Github Flavoured Markdown

Althoug similar, Bookstack does not use Github Flavoured Markdown (GFM) which might be what most users are used to. The admins of this bookstack have added customizations to make the markdown more similar to GFM.

Callouts:

We have added support for GFM callouts. Ex.

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

[!NOTE]
Note Highlights information that users should take into account, even when skimming.

[!TIP] Optional information to help a user be more successful.

[!IMPORTANT]
Crucial information necessary for users to succeed.

[!WARNING]
Critical content demanding immediate user attention due to potential risks.

[!CAUTION] Negative potential consequences of an action.

If these stop working, contact a Wiki administrator and ask them to look at the "Custom HTML Header" for the bookstack. You can also revert to the basic html style callouts which should always work. Ex:

<p class="callout info">An info message</p>
<p class="callout success">A success message</p>
<p class="callout warning">A warning message</p>
<p class="callout danger">A danger message</p>

An info message

A success message

A warning message

A danger message

Back to top