Documentation

{{docApp.title}}

{{docApp.description}}

INDEX

Documentation Library

Search for information on Hornbill Documentation.

{{docApp.searchError}}

{{docApp.searchResultFilteredItems.length}} results for "{{docApp.currentResultsSearchText}}" in {{docApp.searchFilterBySpecificBookTitle}}

Have questions about this site?


What is this site?

  • This website is Hornbill's new product documentation website and is currently under development.
  • It is intended that all existing and future public-facing documentation we produce will be available to search, browse and share.
  • Hornbill's current documentation is available at Hornbill Wiki but over time this content will be migrated to this documentation site.
  • Please feel free to have a look around at any time.

Why has Hornbill created this site?

  • Hornbill's products have moved on considerably since we introduced it almost 10 years ago. At the time, the MediaWiki tool was sufficient, but we have outgrown it.
  • Our customers are more enterprise focused and more self-sufficient than ever before, so for 2023 and beyond we have established a new documentation platform and team to drive our documentation initiative forwards.
  • We are aiming to deprecate the use of Hornbill Wiki for most Hornbill related documentation.
  • We want to enable our growing partner network with product resources and information, documentation beyond our Wiki approach is required.
  • We could definitely do with some help, and may even pay for some! If you have domain knowledge and would like to help, please check out our Hornbill Docs Contributor Guide and contact the Hornbill docs team at docs@hornbill.com.

What will this site be good for?

  • Community contribution will be facilitated, encouraged, and most welcome.
  • High quality documentation, will be kept up to date as rapidly as our products evolve.
  • Real-time content search and discovery.
  • Articles organized into books, books into libraries, creating a more natural and logical structure to our documentation.
  • Legacy API documentation and various other documentation sources will all be consolidated into a single unified documentation system.
  • Documentation available in browser as well as printable/viewable as PDF on demand.
  • Personalized documentation experience, allowing dark/light mode, article subscriptions, social media sharing and other useful features.
  • Almost all publicly available documentation on docs.hornbill.com will be open-source and available to fork on GitHub, allowing customers to derive their own custom documentation around Hornbill products should they wish to.

What is the timeline for this site?

  • We have taken the decision to publish and make available early, there is very little content at this time.
  • As and when we have completed/usable documentation, it will be published here.
  • We have a host of additional features we wish to add over time, so please watch this space.
  • We expect most of our existing documentation should be reviewed/migrated to docs.hornbill.com over the coming months.
  • The documentation project will be ongoing, will continue to expand, evolve and improve day-by-day.

{{docApp.libraryHomeViewProduct.title || docApp.libraryHomeViewProduct.id}}

{{docApp.libraryHomeViewProduct.description}}

  1. {{book.title}}

{{group.title || group.id}}

{{group.description}}

  1. {{book.title}}

{{group.title}}

Getting Started with Contributing

The Hornbill Docs team publishes most of its documentation on GitHub. Each HDocBook has its own public repository, and anyone is free to contribute to Hornbill Docs should they wish. The process is simple and makes use of readily available and free tools—simply follow this guide to learn how.

GitHub

GitHub is an online source code and community projects website for developers, and is primarily used to host open-source projects. Hornbill maintains a GitHub account which we use to host our documentation source code. Almost all documents available on the Hornbill Docs website are made available as a public repository on our GitHub account. You can browse the Hornbill Docs GitHub account here.

In order for you to contribute to Hornbill Docs content, you will need a basic working knowledge of GitHub and a free account.

How Contributing Works

The basic workflow for contributing to documentation on Hornbill Docs is as follows.

  1. When logged into your own GitHub account, you can browse the Hornbill Docs repository, and locate the specific document you wish to contribute to. Once you have located the repository to work on, you must create a “fork”, which will make a copy of that repository in your personal GitHub account. Although this will be a copy of the master document, GitHub maintains a link back to the master source you copied from, and this is what facilitates you being able to push back your changes for review and intake to the master.

  2. When you go to your own GitHub account repository list, you will see your forked copy of the document, this is where you can make your edits.

  3. Now you can make your edits. Simple Edits can be done from within GitHub directly. For more Complex Edits we strongly recommend using a good source code editor, such as the utterly brilliant and free Visual Studio Code editor from Microsoft (along with a small number of very useful plugins) for a great editing experience.

  4. Once you have completed the edits you want to make, you can, if you want to, create a pull request to ask the maintainers of the master document source (in this case the Hornbill Docs team) to accept your edits. The team will review your changes and pull them into the master repo for inclusion in the next nightly documentation build.

  5. Once you have finished your editing session, you can save space on your personal GitHub account by deleting your fork of the document. Forking is fast and simple to do, so it’s easy to take a copy of the latest source when you want to start a new editing session.

Tip

Once you have copied (forked) the master repo, your changes are not applied to the master, so you are safe to do whatever you want. If you do send a pull request, the changes you request will be reviewed by the Hornbill Docs team before being accepted into the master documentation source. The review process will be much faster if your changes are small.

There are two workflows for content editing: simple and complex.

Simple Edits Workflow

For the Simple Edits Workflow you can do everything through the GitHub UI—no additional tools are required. Simple edits are good for when you want to make quick text changes. However, it’s important to understand that while the Hornbill Docs system uses Markdown, there are many flavors of Markdown, and the GitHub UI will not render ours exactly as the Hornbill Docs website will. So for more complex edits/contributions you should follow the Complex Edits Workflow.

Complex Edits Workflow

For the Complex Edits Workflow you will generally install some specific tools, including Git command-line tools or TortoiseGIT Windows shell extension, a text/code editor of choice, Node.js and some other supporting tools. Editing will involve forking in GitHub, cloning your forked copy to your local hard drive, and then using your favorite text editor to make the changes/edits. The advantage of the Complex Edits Workflow is that you can install and use a tool that will give you a live preview of the documentation you are editing, and this preview gives you a lifelike preview of how the documentation will be presented on the live Hornbill Docs website.

Partner Edits Workflow

For the Partner Edits Workflow you will generally install some specific tools, including Git command-line tools or TortoiseGIT Windows shell extension, a text/code editor of choice, Node.js and some other supporting tools. Editing will involve cloning the master repository to your local hard drive, and then using your favorite text editor to make the changes/edits. The advantage of the Partner Edits Workflow is that firstly, you are working directly in the master repository for the document, so you do not need to work about staging and pull requests, you are effectively working as a master document editor. In addtion, like the Complex Workflow, you can install and use an authoring tool that will give you a live preview of the documentation you are editing, giving you a lifelike preview of how the documentation will be presented on the live Hornbill Docs website locally on your computer.

In This Document