Booki User Guide

Communication

When collaborating on a book, communication is a vital part of the process, whether working in a book sprint, taking your time on more long-term book generation, working locally in the same physical space or remotely online. These situations have different requirements and harmonising these into one system is where FLOSS Manuals has done a lot of real world research and Booki takes the best of what we have learned. Booki includes tools such as real time edit notifications to see who is editing what at this moment, a real time chat (web / IRC gateway), system level notifications, chapter status markers, book progress indicators, work flow tools, and live user status listing

Real time edit notifications

When you have clicked on an edit link for a chapter and someone else enters the books Editing screen your user name replaces the EDIT link in the Table of contents. This notification happens in real time, if you are looking at the overview screen when someone else clicks the edit link for one of its chapters you will see the edit button change to their user name.

Real time chat

Upon entering a book's Editing screen you will see a chat box for that book. The Chat is visible for the duration of the time you are editing the book, regardless of which chapter you are working on. Anyone else editing the book also has the chat box and you are able to communicate with them by typing directly into the text field under the the chat box. This feature is very useful for communication with remote participants in Book Sprints as well as any situation where contributors to are book are working on it simultaneously.

Other information is also communicated through the Chat box. When a contributor enters the book editing screen a JOINED marker is displayed along with their name in the Chat box. So anyone already editing a book can see that someone else has joined them in editing mode and they can start communicating.

Live User Status Listing

Below the chat box is a Currently editing panel which lists all authors currently working on the book. As an added feature of this panel not only is the users name listed but also a "What's on your mind ?" statement, which is edited from your Profile page. This statement can help communicate to others what you are working on (e.g. "I'm touching up formatting in the Introduction"), or how you are feeling (e.g. "Having bad day, don't want to talk...TO ANYONE").

System level notification

System Level Notifications are generated when the following actions are performed:

  • When a user saves a chapter
  • When a user creates a new chapter
  • When a user renames a chapter
  • When a user alters the status of a chapter
  • When a user creates a new section
  • When a book is being published
  • When a user saves a book's notes

Booki generates and displays the messages in two ways: using the Chat Box and using the History Tab in the Editing Page.

Chat Box

When one of the above actions is performed the Chat box displays an INFO marker and brief description outlining what has taken place. This Notification is extremely useful in a Book Sprint environment where several participants are collaborating on a book simultaneously. Each participant is kept up to date of others' progress and can instantly reply to any notifications using the Chat Box.

History Tab

The History tab sits next to the Chapters tab in the Book Editing Page. Clicking to the History tab loads up a list of all the edits that have been made to the book (Note: on a mature book it can take a while to load the list due to the large number of edits that have been made). Every time one of the above actions is performed a new item is added to the history tab.

The History Tab is divided into 3 columns: action, user and time. The action column lists the type of action that has taken place and if necessary it includes extra detail regarding the action. For example if the action recorded is create or save then the detail will list the name of the chapter that was created or saved. The user column lists the Booki user who has performed the action and the date and time of the action is recorded in the time column.

To see more detail a user is able to click on the underlined chapter name in the action column which loads a history page for that particular chapter.

If an edit to a chapter has been very minor, for example a spelling correction, the author has the option to prevent a history record from being generated when the chapter is saved. This is carried out using the Minor change, don't notify tick box at the bottom of the Chapter Editing panel. Placing a tick in the box will prevent a history record from being generated when the chapter is saved.

An author also has the ability to add comments to the history record using three text boxes below the Minor change, don't notify tick box. The top box is a general comment box, followed by an Author text box, where the Author has the option of entering their name. The final text box is an Author comment box where the author is able to make another note. Comments entered into any of these text boxes will be added to a history record when the chapter is saved.

Chapter History

The history tab not only lets you see the changes that have happened to the book but it also allows you to view the changes that have happened to individual chapters. Clicking on a chapters name in the action column takes you to a chapter history display. Here you will see a list of all the edits made to a chapter from it's first creation down to the most recent revision. The Chapter History lists the revision numbers with the most recent revision at the top, it also includes the user who edited each revision, the time and date the revision was saved and also any comments made by the author in the general comment box mentioned above.

Using the compare column on the left you can review the differences between any two revisions. Simply select the left radio button for one chapter and the right radio button for the other chapter you want to compare, then click on the Compare revisions button to see the differences between the two chapters.

The records in the history tab can be very useful for working on a book over a long period of time where contributing authors are often not logged into Booki at the same time. It can display what edits other authors have contributed since the last time a participant logged on and help them to decide what areas to work on. This is especially true if the author has added comments detailing what they did and what further work they feel is needed in order to complete the chapter they have contributed to.

Chapter status markers

In the Chapters tab of the book editing page, on the right hand side of each chapter bar there is a status marker for the chapter.

This can be manually altered depending on what stage the chapter is up to. Clicking on the marker reveals a drop-down list. Click on the list and select the status required for the chapter. The chapter's marker is changed to the new status.

When working on a book that has been created from scratch, the default marker is not published. For a book that has been imported from another source, the default status for a chapter is imported even for new chapters that have been created from scratch after the import.

Book Notes

A books notes are where contributors can discuss and add comments about the book as a whole. Anything can be added to a book's notes including a suggested structure or outline for a book, which areas need urgent attention and even suggestions for a books direction. Book Notes are accessed through the Notes tab on the Book Editing Page. Once there you have a free text field to add a much or as little as you want. When you have added your notes, click Save the notes at the bottom of the Notes tab to save your changes, an INFO notification will be displayed in the Chat box saying that the notes have been saved.

Use Case

You log into Booki to make some additions to your book "Growing Vine Fruit", when you load up the Editing page you notice that another member of the Organic Gardening Group is already editing a chapter on Pruning as their name appears instead of the Edit Button for the Pruning chapter in the Table of contents. You use the chat bot to hi to the other Author and two of you have a brief conversation about the structure of the book before start on your own edits.

While you are typing away you suddenly see an INFO icon pop up in the Chat box saying that the other Author has saved the chapter "Pruning". A couple of minutes later you see their name disappear from the Currently editing panel below the Chat box, this reminds you of some ideas that came up in the conversation you had earlier. You think these would be good to share with everyone working on "Growing Vine Fruit" so you save your work and then click on the Notes tab. In the notes tab you type in a couple of sentences outlining a revised structure for the book. Now any other Author will be able to click on the notes tab to find out the proposed structure for the book and even make their own notes or additions.

Once you have finished your notes you decide that you want to compare the other Author's modifications to the "Pruning" chapter with an earlier revision. You click on the history tab. At the top of the history list is the changes saved to the "Pruning" chapter. You click on the chapter name in the list which loads up the chapter history listing every revision of the chapter saved. To compare the differences between the two most recent revisions you click on the left radio button for the latest revision and then the right radio button for the next revision down, now click on Compare revisions. The revisions are displayed with mark-up showing what changes have taken place in the latest edit.