Tools

There are several tools we use as part of our documentation process. Whether you’re looking to gather information for a doc, write it, or ready it for peer review, there exists a tool for every step of the process. While some tools are standard for the team, others are up to the individual team member to decide what fits their workflow best.

Git

Banno uses GitHub as its primary tool for version control of its source code and documentation. This is where the repositories for our docs reside, and peer review can be requested.

For setup in the terminal, simply type git and you’ll be prompted for an install if it is not already installed. If you’re new to the terminal, GitHub Desktop provides a nice alternative in a desktop client with a full user interface.

For more information, please see the GitHub guide on our internal wiki, as well as Git’s help page, for more information, including setup and usage.

Repositories

The documentation team primarily works in two Git repositories, each with a distinct focus:

• The knowledge repo is used for all customer-facing docs.
• The wiki repo is used for internal docs relevant to the Banno group within JHA, as well as individual teams within Banno.

Editors

When it comes to writing documentation, there exists a wealth of text editors available to use. None are required, so you are free to choose whichever editor you prefer. We write our docs in Markdown format, so it’s advised to choose an editor that works with its syntax. Below are a few text editors used by our team.

VSC

Visual Studio Code is Microsoft’s text editor, supporting Markdown previews, bit support, auto-complete, and more. The built-in extensions allow you to add support for any syntax needed.

Atom

Atom is an open source lightweight text editor developed by GitHub that can be used for writing code in addition to documentation. Out of the box, it supports Markdown syntax highlighting and Markdown preview. Markdown preview is a nifty tool that allows you to view a rendered version of your doc as you type it. The shortcut to activate (and deactivate) the preview is ctrl-shift-m.

Other editors

These are the editors we use, but you can use anything that will allow you to edit Markdown files. Feel free to use any editor you find easy-to-use, and if you need help, you can always ask in #team-docs.

Slack

Slack is our primary messaging client at Banno. The bulk of our quick asynchronous communication happens in Slack through channels and direct messages.

Channels can be thought of as a group chat regarding a specific topic, like a team or product feature at Banno. The documentation team has two Slack channels dedicated to it:

• team-docs is a private channel involving just the documentation team members.
• org-documentation is an open channel for any Banno team member to discuss the organization’s documentation.

For more information on how we use Slack, please see the general onboarding page.

Jira

Jira is an issue-based board used for managing work at Banno. It allows us to view any work available to be assigned to our team, as well as the progress of work assigned to an individual team member. The progress of a project (or “issue”) can be tracked once assigned in columns like In Progress, Needs Review, and Done.

The documentation team board can be found here.