posted last year in CUBRID Life category by Esen Sagynov
Today I would like to introduce the online tool we have recently found and started to use to write and manage the Release Notes for CUBRID Database. I will explain about the tool we used to use and the difficulties we had to deal with before adopting the new solution. Then I will explain about the features of the new tool which I think will be very beneficial to manual and documentation writers.
Originally we have been writing and distributing Release Notes in MS Word and have it edited and reviewed by multiple users. It provides nice changes tracker with features to accept or reject changes. Formatting in MS Word is very advanced, which is probably the biggest reason why we prefer it over other editing tools. References management in MS Word is great, too! You can also export documents to a PDF format very easily. This is what we used to do to distribute CUBRID Release Notes. MS Word is a really great tool if you need to manage your document in this way.
But what was continuously tedious for us with this solution is the transformation to the Web format. As most of you may know, MS Word adds tons of garbage tags when exporting to the HTML format. It's very difficult to clean them up. Moreover, the exported format does not seamlessly integrate with your existing site style, provides no mobile optimized view, so you end up either spending much time cleaning MS Word output to fit your existing site design, or simply adding a link to a PDF file.
Alternatively you would look for a solution which would export MS Word document to HTML with consistent styles and provide you with similar editing experience. We did much research on this and found 3Rabbitz Book, a 100% Web-based Enterprise Authoring Tool.
About 3Rabbitz Book
3Rabbitz Book is a shareware online editing tool ideally designed for multi-author environment to work with long documents and manuals. It is free for personal usage up to 3 simultaneous editors. You can review the pricing on their site. The great news is that the 3Rabbitz Book developers also provide a free license to open source projects and non-profit organizations. If you are after a commercial license, they provide a 30-day free trial as well.
With 3Rabbitz Book we started to spend more time writing the actual content rather than spending time on editing an MS Word document, converting to HTML, then cleaning up the HTML output every time we need to update the document. 3Rabbitz Book provides many great features. I will try to explain some of them below.
Web-based editing tool
Since it work in a browser, writers are not limited to working on a particular computer or operating system where the editing tool is installed. Wherever there is an Internet connection, you can make changes and publish your document to the Web instantly with 3Rabbitz Book.
3Rabbitz Book can be used by multiple authors at the same time and their work can be revised and then merged into one. 3Rabbitz Book provides a convenient collaborative environment for authors.
Dividing a manual into chapters
It is very inconvenient for multiple authors to write a manual with a word processor. This is because they should repeat the cumbersome process of splitting a file into many parts among writers, then writing each part separately, and then collecting them back into one file through a file server or mail. In this process, contents are sometimes omitted, and it takes effort to standardize inconsistent forms.
With 3Rabbitz Book authors can divide the document into multiple parts/chapters. Each author fills out the selected content. However, unlike MS Word, you don't need to collect individual parts from all authors and compile them manually into a single document. For example, you can organize a table of contents as shown below.
Figure 1: Dividing the manual among authors.
Paragraph level editing
3Rabbitz Book provides paragraph level editing which has the following advantages:
- Multiple authors can edit the same chapter simultaneously.
- You can do structural writing.
- You can manage the history of changes.
- You can separate content and form.
Also the editor minimizes the use of a mouse and provides a variety of shortcuts so authors can use only a keyboard.
Figure 2: 3Rabbitz Book Editor.
Single source publication
One of the great features we love in 3Rabbitz Book is the publish once and distribute in multiple formats feature. On your site you can provide a link to your site visitors to export the manual to PDF, EPUB, or other formats suitable for Web, print and mobile devises without additional editing overhead. Awesome!
Exporting to HTML
Other manual writing tools like MS Word also support "Export to HTML" feature, but like I said before, they have problems:
- They support only limited HTML. You cannot change forms, or have to go through a complex process to accomplish that. You may need to export XML first instead of HTML and invest additional time and effort to create proper HTML through another tool.
- Some display HTML within frames while the table of contents is provided in the parent document for navigation. Search engines, such as Google, may fail to search such output as HTML content is loaded in AJAX.
- Whenever you update HTML, you must upload HTML files on the web server via FTP. To carry this out, you may have to use addition software apart from a content writing tool.
On the contrary, with 3Rabbitz Book you can write HTML and publish it on the web and make any changes to it in a real time. You can also design a form of the Web viewer (an output viewer) in a variety of ways and they are search engine friendly.
The main components of the Web viewer are as follows:
- Displays the order of titles, figures and tables.
- Provides a built-in search field.
- Displays an index. An index will appear only when there is an index type chapter.
- Provides links to Download PDF and EPUB formats.
Figure 3: Web Viewer.
Exporting to PDF
While many Wiki products do not support Export to PDF feature or are unable to create a single finished PDF file, 3Rabbitz Book enables you to create a high quality PDF file composed of all parts of the manual in the right order, including table of contents, figures, tables, appendix, etc.
Unlike other manual writing tools, you don't need to separately upload a file to a Web server to generate a PDF file. The following example is a screenshot of a PDF file created with 3Rabbitz Book. Check out the preciseness of the PDF it produces.
Figure 4: PDF output of 3Rabbitz Book.
Figure 5: TOC in PDF file.
Figure 6: Manual Chapters in PDF generated by 3Rabbitz Book.
Exporting to EPUB
Exporting to EPUB is a really cool feature which is very crucial in this mobile heavy world. Unlike other manual writing tools, you don't need to upload an EPUB file to a Web server to distribute it to users. The manual author can generate an EPUB file which will be automatically saved on the server. The following examples are screenshots of an EPUB document from an iPad created with 3Rabbitz Book.
Figure 7: EPUB file generated by 3Rabbitz Book.
Figure 8: Clean EPUB pages auto-generated by 3Rabbitz Book.
Separating contents and forms
To create a good manual, you must maintain a consistent look-and-feel. When you use a word processor, it takes a lot of effort to maintain a consistent form. The form varies depending on who writes a particular chapter or when it was written. Unless a single person takes the responsibility to standardize different forms on a regular basis, the gaps in these forms will keep increasing and inconsistent numbering and references to headers may occur while combining files.
On the contrary, 3Rabbitz Book separates contents and forms thoroughly. In 3Rabbitz Book you cannot insert form information while writing a content. Instead of configuring a paragraph indent or a margin between paragraphs, you can select a type, give a significance and configure a form in a lump as a theme. This is called a paragraph type.
Figure 9: Setting a Paragraph Type.
You can also configure a form in a lump as a theme after assigning a significance, rather than configuring a font color or bold to a certain string. This is called a character type.
Figure 10: Configuring a Character Type.
When viewing a content on the Web viewer or creating a PDF file, if you select a theme and a layout, the final document is produced according to the configured paragraph and character types. In the form menu comprising of themes and layouts you can design the form of the Web viewer, PDF and EPUB files in a variety of ways.
Figure 11: Selecting a Theme and a Layout in Exporting PDF.
You can store the entire editing history and maintain documents safely even during a collaborative editing through the feature of history comparison and deleted paragraph restoration.
Figure 12: History Comparison.
Putting Callouts on Pictures with Visual Editor
When you write a software manual, sometimes you need to put callouts to screenshots. You can do it simply with the Visual Editor.
Figure 13: Visual Editor.
Also with the Visual Editor you can write the following content by using the "callout list" paragraph type and the "callout" character type.
Figure 14: Paragraph Callouts in 3Rabbitz Book.
Automation and Reuse
3Rabbitz Book supports automation for a variety of items.
- Creates a PDF title page and the first page automatically.
- Creates the order of titles, tables and figures automatically.
- Creates indexes automatically.
When you create multiple manuals with similar contents, some redundant contents will occur. 3Rabbitz Book provides the feature to reuse them effectively.
- Can reuse content in the unit of chapters.
- Can reuse content in the unit of sections or paragraphs.
- Can refer to image paragraphs.
- Can use themes and layouts in multiple manuals.
Easy Installation and Update
You can install 3Rabbitz Book simply by decompressing the setup file and configuring options with the Web-based Installation Wizard on a variety of OSs, including Windows, Linux, Unix and Mac.
As 3Rabbitz Book is a server application developed in Java, it supports those operating systems which can run Java 6 or higher versions.
Figure 15: Installation Wizard.
After checking for a new release, you can update 3Rabbitz Book simply with a few clicks and a server restart.
Figure 16: Software Update.
I hope 3Rabbitz Book can be a satisfactory solution for authors and projects out there who could not find a way to overcome the inefficiencies in writing a manual whenever a new product is released or a service is upgraded.
We are very thankful to 3Rabbitz Book developers for providing us a free license. For more information about using 3Rabbitz Book, see the Installation Guide or the User Guide. You can also write an email to email@example.com if you would like to directly communicate with the developers.
We also found another solution called FrameMaker by Adobe. But we could not try as it costs 999 USD. If you have any experience with this tool or any other tool, please share your experience in the comments below.