Atlassian finishes redesigning its API reference pages with a three-column layout

A redesign now covers every API page

Atlassian, the company behind work tools such as Jira and Confluence, has finished rolling out a redesign of its API reference pages, as atlassian.com reported. The work began in April, when the new look first appeared for the Jira Cloud and Confluence Cloud references. It now applies to all of Atlassian's API reference pages.

An API (application programming interface) is a set of rules that lets one piece of software talk to another. An API reference is the manual that lists what you can ask a system to do and how to phrase the request. Developers consult these pages constantly, often in the middle of building something else, so small annoyances add up quickly.

Atlassian says it believes the update will make the pages easier to navigate and make it simpler to find information and use the APIs effectively. That is the company's own expectation. The announcement does not include measurements of how much faster people can now work.

What was wrong with the old pages

Atlassian listed four problems it had identified with the earlier design. Each is familiar to anyone who has fought with a dense manual:

• The pages packed in so much information that it was hard to scan for essentials, such as which parameters (the settings you must supply with a request) are required.
• On smaller screens, readers had to scroll back and forth between the explanation and the code samples.
• It was hard to find the right endpoint, especially for resources with many of them. An endpoint is one specific action or address you can call.
• The design was starting to look dated.

The first three are about speed and confidence rather than looks. A developer who cannot tell at a glance what is required may send a bad request, then lose time working out why it failed. The fourth is cosmetic, but Atlassian lists it alongside the rest as part of the case for a refresh.

How the new layout works

The biggest change is a three-column layout. The left column holds a revamped navigation menu. The middle column carries the main content: detailed explanations of each endpoint, its parameters and its query options. The right column shows code samples and responses that match whatever is being described in the middle. Atlassian says this keeps related material side by side, which helps people absorb it.

To tackle information overload, the team used what it calls progressive disclosure. That means showing the most important facts first and tucking the rest away until someone asks for it. By default, readers see things like 200 responses (the standard code for a request that succeeded) and top-level parameters. Parameter descriptions, child properties and error responses appear after a click.

The team also changed typography and information design. In section headings, required parameters and response types stand out through a mix of spacing, font weight and color.

Navigation got two practical upgrades. A version menu now sits in the navigation panel, so readers of REST APIs that have more than one version no longer need to switch tabs. And the page tree, the list of operations, has been updated so you can quickly see which method each operation uses and whether it is deprecated (being phased out) or experimental.

Who feels the difference and what is next

The direct audience is developers who build apps and automations that connect to Atlassian products. If you are not one yourself, you may still feel the effect indirectly. Better documentation tends to make it easier for the people building those connections to get them right, though Atlassian does not claim anything specific on that point.

The changes also illustrate a design idea worth noticing. Rather than cutting information, the team reordered it: essentials first, detail on demand. The same approach works in many places where a lot of material has to reach a busy reader.

Atlassian says the work is not finished. It is asking for opinions on the redesigned pages, along with suggestions for further improvements or new features. People can respond through the Atlassian Developer Community or by using the 'Give feedback' button at the top right of the new pages. The post does not say what changes might come next or when.