How to use (and contribute to) this Wiki

Creating your account

First of all you need an account. This can happen in 2 different ways:

- A wiki admin created an account for you and provided you with credentials to access the wiki. Nothing to do here but, if you can't edit any pages in the wiki, it is possible that the wiki admin forgot to give you editing permissions, please remind him/her.

- You can create the account yourself by going to https://wiki.oceanbuilders.com/register and filling up the form. An email will be sent to you with a Confirm Email link on it. It is a necessary step to confirm you are the owner of the email address. Once your account is created you need to do one more step: please ask your coordinator for editor access to the wiki, because after the account is created you cannot edit any documents or add any documents until you are given permission to do so.

Wiki organization

This wiki follows a very simple organization: Shelf > Book > Chapter (Optional) > Page

Every document created in this wiki is a page. A page can optionally be contained inside a chapter together with other pages, or it can be directly created outside any chapter. All pages and chapters are contained inside a book. Books are organized insider Shelves.

At the top of each document you are browsing you will be able to see where exactly you are located in that hierarchy. For example here is a Page that do not belong to a specific Chapter:

and here is an example with a Page that is contained in a Chapter:

Understanding roles and permissions

This wiki is setup with multiple user roles. Each user role has a different set of permissions defining what they can do and cannot do in the wiki. Only admins can create new user roles or modify the permissions of a role.

Using roles allow us to have all the content in the wiki while keeping it secure.

If you think your user needs a role with more privileges or if you think we should have different roles organization, please ping your coordinator.

Here is an example showing what the Book Editor can do and cannot do:

But there is more!

Permissions can be set individually to each Self, Book, Chapter and Document. These permissions have priority over the role permissions. However it is not recommended to abuse this practice, because it can get quickly hard to keep track of what are the individual permissions in each book, shelf, etc.

Example of how this useful: we want to have user role "Legal Team" that will have users only interested in editing stuff related with the legal side of the organization. We still want them to be able to see everything, but we don't want them to be able to edit anything outside the "Legal" book.
First we create a role "Legal Team" with the following permissions:

We can now give that role to all the people that will take care of the legal documentation. At this point they can see it all, but they cannot edit anything.

Now we navigate until the "Legal" book and we click in "Permissions"

Here we give them permissions to edit and create anything inside the book:

Hiding documents to people without an account

If you create a Page or a whole Book that you consider that should not be public (visible even without an account) please edit the book/chapter/page permissions and make sure that nothing is enabled for the "Public" role.

In the same way, if you think a document should only be visible to a bunch of people, you can do it in the same way, disabling all permission except for those user roles that should be able to see it.

If you just copy the URL of the page you are browsing, it is possible that in the future (with changes in the name page that affect the URL) the link won't work. Instead share permalinks. It is very easy, just select some part of text in the page and you will see a permalink to the page.

More about permalinks here https://www.bookstackapp.com/docs/user/content-permalinks/

Editing your Pages

The editor doesn't need a big explanation, it is the standard WYSIWYG editor that you already know. Use the full screen button to be more comfortable!

Inserting code

If you are a developer and you want to insert blocks of code, don't forget there is a special formatting for code. You will find it under Formats > Code Block

Tag your pages! (and books and chapters)

Tagging every page in the wiki is a helpful goal. Please do tag your page before or while editing it. You just need to open the tag button in the sidebar and insert your tags there. You can also reorder them.

Why is it important?

It helps with searches. It also shows on the left side when you open any page to viewing, so it quickly gives the user an idea of what is it about.

Tags can also be inserted in books and chapters that you create.

A tag can have just a name, or can also have a value. So you could for example add a tag "difficulty" and then in different documents with that same tag you might give different values to it: "medium", "easy", "super difficult".

Using templates

This wiki has a useful template system, use it! It is fairly easy:

Create a Page that will contain the template. It will be like any document except that you will only place the structure of the document, or whatever you think your template needs, and then tag it as "Page is a template". For that all you have to do is to open the Templates button in the sidebar:

and then check the "Page is a template" option:

Then just save the Page as you would do with any other document.

Now use your template!

Create the page you want in the book/chapter of your preference. Initially the page will be blank. Now go again to the templates button in the sidebar and you will see there your template together with other templates created by other people:

That's all!

Reusing page content

This is well explained here: https://www.bookstackapp.com/docs/user/reusing-page-content/

Basically a page can embed another page easily. Or even portions of another page.

Page revisions

If you need to go back to a previous version of your Page you can do it with the Revisions feature. To find it make sure you are not editing the document. Instead you should be viewing the page. In the ACTIONS panel you will find the Revisions feature:

and it will look like this:

so you will be able to see what changes were done and restore it if needed it.

Re-organizing content

This wiki allows you to move content from one place (book, shelf) to another and to reorder content.

In the current version we cannot change the order of the shelves. But we can change the order of books inside a shelf, chapters, pages.

Re-ordering and sorting

To reorder Pages and Chapters just go to the book you want to reorder for and use the Sort button in the Actions panel:

You can sort or do manual ordering by drag & drop.

If you want to reorder books inside a shelf, go to the shelf and click on Edit:

Move content around

To move books from one shelf to another you have to go to the destination self (shelf you want your book moved to) and click on EDIT. You will see a "Add books to this shelf" panel listing all the books. Drag & Drop the one you want to move to the left panel.

To move pages to another book go to the page you want to move and click on "Move" in the Actions panel. You will see a list of books and chapters that you can move your page to.

Advance search

This wiki has a very good search engine. But at a glance it can seem pretty simple. Simply click on the search field at the top and hit Enter and you will see a rich variety of search options.

One not so obvious feature of the search is that since tags can be assigned different values you can search by specific tag values like this:

For example you could search documents with tag "status=pending_review" using this feature.

More about advance search here https://www.bookstackapp.com/docs/user/searching/