Announcing beta

Reading Time: 3 minutes

Why are we doing this?

The user experience on our developer site was fragmented and inconsistent. Before we drew our first mockup, we took a long, hard look at our docs. We also conducted user research, reviewed user feedback, and came away with a few design principles:

  • Improve search and navigation
  • Update stale, out-of-date content
  • Refresh the design with our users in mind

Start small, then go big

Atlassian is known for using Agile methodologies for developing software, so it should be no surprise that we’ve taken a similar approach to building our new developer site. This is why the beta release focuses on a single area of our content: the JIRA Cloud dev docs (JIRA Cloud platformJIRA Service Desk Cloud, and JIRA Software Cloud.

Focusing on one area allowed us to think through the navigability, searchability, and overall experience of using our content. Let’s take a look at a sample page:

The design of the sample page above highlights several of the key usability issues we found in our content, namely the fragmented experience. Previously, you would have been forced to navigate between three different areas of our site to access content for a particular product. Now you can easily navigate between developer guides, reference information, and API content while staying in context.

The little things matter, too

We also accounted for some of the little, every-day usability quirks specific to using dev docs. For example, during user research we discovered that our users love using Ctrl+F to search within documents and that scrolling past lengthy code blocks is frustrating.

Here are a few examples of the many small usability improvements you’ll find in the beta version:

  • Code blocks with syntax highlighting (and max height)
  • Last updated date on every page
  • Flat navigation for easy on-page searching
  • New text callout styles for info, warnings, and notes

Community contribution

There are loads of great new features in the updated site, but my personal favorite is the addition of community contribution via pull request. This means that you can now contribute directly to our developer docs with a click of a button.

After you submit the pull request, a content expert on our team will take a look.

Note: You’ll need to sign the Contributor License Agreement and sign in to Bitbucket in order to contribute content as shown above.

Technical highlights

The new platform brings the writing process closer to our developers and uses tools we use every day. Our dev docs are now stored in Bitbucket, making it easier to update content in line with code changes and integrate with auto-generated docs. It also makes it easier for our extended developer community to contribute via pull requests.

We standardized on using Markdown and chose Hugo, a modern static site generator, for publishing. Hugo is written in Go and has a flexible templating architecture, out-of-the-box Markdown extensibility via short codes, and powerful data presentation. These features allowed us to tick most of the boxes in our requirements without extending Hugo.

We are using Foundation for the grid and some UI components (such as the carousel and the drop-down menus), and we developed a React, ReduxBabel, Webpack stack for the front-end, which over time will be expanded in use and functionality.

Send us feedback!

We’d love to hear from you as you explore the beta. You can share your feedback with us during the beta using our new Ecosystem developer service desk. The updated JIRA Cloud docs are just the start. We will be migrating all of our developer content to the new site as well as introducing some exciting new features in the coming months.

What’s next?

Our team has put a lot of effort into redesigning this site, and there are many more improvements coming. The content will be migrated to the new site one section at a time, and we will be enabling features, such as automated testing of code samples.

That’s all for now. We look forward to hearing your feedback!