Background to Publishing on Hornbill Docs

To understand the process of creating a new Book, it’s important to have a clear understanding of what the Hornbill Documentation system is. Fundamentally, the Hornbill Docs platform is a documentation publishing system, specifically designed for publishing official Hornbill documentation to the Hornbill Documentation website.

Hornbill’s documentation system borrows the concepts of physical paper book publishing, something very familiar and intuitive to most of us. The Hornbill documentation site is our “public library” of documents, and just like a physical library, in our digital library, we organize individual units of documentation as “Books”. Each Book is made up of one or more individual articles (think pages or chapters), with a “table of contents” that organizes the article(s) into a navigable structure, much like the table of contents does that you find near the front of in a traditional paper book.

Part of the Hornbill Docs system is a taxonomy, which you can think of as the classifications and organized areas of a physical library (such as literature, physics, computer science and fiction). The taxonomy is used to tag and group collections of Books and organize them into a logical, easily navigable document Library.

The Hornbill Docs team assumes the role of the “publisher”, making sure that:

• Book titles are relevant and well organized.
• Content is not duplicated.
• The taxonomy makes sense.
• Library is well laid out and easy to navigate, even a large number of books.
• The compiled Library is searchable and easily accessible by the intended audience.

First Question Before Creating a New Book - Do We Really Need a New Book?

Before creating a new Book, the Hornbill Docs team must decide if the book it is needed. Unlike a physical library with paper books, the Hornbill Docs system uses a digital medium making it very easy to add or update existing Books’ content. In fact, most Books published on the Hornbill Documentation site are published as open source on GitHub so that anyone that wishes to contribute, can follow the Simple or Complex Edits workflows in order to do that.

The reason why this question must be asked, up front, is that the Hornbill Docs team must be selective about what new Books it will accept for publication on the Hornbill Documentation website. This is because, just like a physical book publisher, the Hornbill Docs team want to ensure the quality, relevance and consistency of each Book in the Library. Any new Books will need to deliver standalone value, not (substantially or in part) duplicate existing content, and, the book should be generally additive to the body of knowledge in the Hornbill Library. The Book will need to fit into its taxonomy and should substantially cover topic(s) that are not already covered by existing documentation.

A New Book Proposal

The starting point for any new Book to be published on the Hornbill Docs platform is the New Book Proposal, a formal request to the Hornbill Docs team outlining the information about the Book that you want to create. Once you log into the Hornbill documentation site, you will find an option under the “Contributing” menu to “Request” or “Propose” a new Book. Each option will present you with a series of questions to help the Hornbill Docs team evaluate your request. Typically, customers or other users may request a new Book be created to cover the topic(s) they feel are not already covered in other documents. A proposal, on the other hand, would come from a subject matter expert who would be the originating author and create the Book content.

When proposing a new Book to be published, the following information is required:

• Book Title
  • The most important attribute of a Book, the title is what will appear in the master index, search results and other key areas of the documentation system. The Book title must be meaningful and relevant and fit within the overall Library index structure.
• Synopsys
  • Just as important as the title; one to five paragraphs setting out the purpose and topics for the Book to cover.
• Audience
  • Must define the target audience in accordance to the Hornbill Docs taxonomy specification.
• Table of Contents (optional)
  • Ideally this would be useful at proposal stage, but we understand that it’s often not possible.

Once the Book has been proposed, the Hornbill Docs team will review the proposal and either accept it for creation, or, provide feedback on what needs to be changed in order to achieve acceptance.

Writing a Book for Hornbill Docs

We recognize that not everyone is an aspiring author or technical writer, and it’s often the case that those who are subject matter experts are not writers and do not enjoy the process of writing documentation. The Hornbill Docs team will look at the writing needs on a Book-by-Book basis to figure out the best way to go about creating and developing any given Book. In some cases, the Hornbill Docs team may take on writing the Book, working with internal Subject Matter Experts to extract and capture knowledge required, or, we can use external writers or independent subject matter experts, or, any combination of those things.

If you want to write a Book but do not have the writing chops, that’s also ok; write what you can and the Hornbill Docs team can expand, develop and evolve that content. The main goal is always to capture valuable content and ensure that we create the very best-quality documentation to help our customers, partners and the teams at Hornbill.

With any contributions, the Hornbill Docs team will always run content through a process which includes proof-reading, fact verification and copy-editing to ensure information presented is high quality, unambiguous and appropriate for the intended audience.