Skip to main content

Tools and Setup

Overview​

To get set up as a documentation writer for this repository, the following tools, packages, and extensions are recommended to be set up on your system:

  • Git for Windows
  • Visual Studio Code with a documentation writer profile
  • Atlassian extensions connected to Bitbucket and Jira.

The deployed documentation is styled and built with Docusaurus and you can optionally install tooling on your system to build and run a local version of the server. This isn't required for normal authoring, but can be useful if you are changing styling or other framework related code.

Required Accounts​

Make sure you have access to Superna's Jira and Bitbucket instances. Talk with your team lead if you don't have this yet.

Git for Windows​

You can use whatever Git tools you want, but for easily getting started, installing Git from the main Git source is the most reliable way. Run the Windows installer on your system.

Follow the instructions to get Git set up, add your credentials to Bitbucket, and then clone this repository:

git clone git@bitbucket.org:superna/public-documentation.git

Visual Studio Code​

Install Visual Studio Code from the windows app store, or other sources. Make sure it's Visual Studio Code, not simply Visual Studio, as those are two different things.

Once VS Code is installed, open the public-documentation folder that was cloned in the previous step. In VS Code, enable the doc writer profile by creating a new profile from the built-in Doc Writer template, and activate it.

The guide on writing and editing Markdown is useful.

Atlassian Extensions (Jira and Bitbucket)​

To interact with the source code, you can use regular Git processes if you like. However, the Atlassian extensions provide very useful features for branching, starting work, submitting pull requests, and monitoring the build status.

Installation from the vscode marketplace​

Open the extensions tab, and search for Atlassian. Install the Jira and Bitbucket (Atlassian Labs) extensions:

Atlassian Extensions

Once the installation is finished, a tab will load (click on the extension if it doesn't). Click on the gears icon to manage.

Extensions Setup Screen

On the settings UI, login to Jira Cloud and Bitbucket Cloud from the associated tabs. A browser will open to authenticate to the two services. Follow the instructions there.

Login to Jira Cloud

Login to Bitbucket Cloud

draw.io VS Code Extension​

To create and modify diagrams in the code, use draw.io. There is a free VS Code extension in the VSCode Marketplace that you can install into VS Code to enable diagrams to be created and edited in the source.

NodeJS​

Install the latest version of nodejs available

From VS Code open the command prompt from the file menu Terminal -> New Terminal

In the terminal, run npm update. If you get command not found or associated errors, reboot your computer. npm update can take a few minutes to run to completion the first time you run it.

After that completes, run npm start and see the docs in action!