Help us help you find what you need faster - A quick experiment

The Forge content team want to make it easier for you to find what you need in our Forge documentation so that you can build amazing apps faster and help solve problems for your team.

We’re thinking of giving our documentation structure a bit of a makeover to make things easier to find and browse through. With these changes, we’re hoping you’ll have a smoother experience with our Forge documentation and be able to get sh!t done, faster.

We need your help:

We are using an online testing tool to run a study to assess the navigability of our Forge documentation using a site outline. This evaluation will focus solely on the categories and concept groups within the content set, without delving into a detailed analysis of the information architecture.

What we want to find out:

  • Do the labels make sense?
  • Is the content grouped logically?
  • Can you find the information you want easily and quickly?

Here’s how it works:

  1. You will be asked to complete a task and presented with a list of links.
  2. Click through the list until you arrive at one that you think helps you complete the task.

In total, there are 10 tasks to complete and this should take between 10-15 minutes.

You can help us using this link: Start the study!

If you have any general feedback or comments about this proposed new way of organising our Forge documents, please leave comments on this post.

The experiment will run for 1 week and close on 26 March '24.

Thank you for being awesome!


Thanks for reaching out to the community @ShionaWebster!

I have completed the study and found the deep nesting of menus generally makes it difficult to find things. Some groupings, like the “legal” menu under “essentials”, did not make sense to me at all.

In my opinion, Atlassian’s developer docs need a clearer structure in general. They are too heavy on tutorials, which are inherently hard to search, are outdated the day after they are published, and require a lot of work to maintain (I have voiced this opinion before). Instead, the focus should be more on guides and references that generally don’t change so fast and provide much more depth than a tutorial ever can.

This website is a fantastic resource on how to write and structure technical documentation: It may also be worth taking inspiration from big doc sites like Google Cloud, which, in my opinion, do a fantastic job of structuring content into guides, references, samples, and resources for each platform service offering.


I’d like to second @tbinna’s post. Thanks for asking for our feedback about this, I appreciate it :slight_smile:

I’m hoping the study tool is collecting how much I had to search for some things because their placement did not make sense to me.

My personal default behavior for looking things up is pretty much start with the reference and that is fine for me. But: I’d like to point out that I have a decent amount of years of Atlassian Ecosystem experience under my belt, so I might not be in your target demographic if you want to reorder the guides. The Reference ordering makes a lot of sense to me as it is today.

My biggest ask is to keep the reference separate from the guides and tutorials and to instead add more links between possibly related guides and APIs.

For example, the page does mention that this manifest section is relevant to the External Authentication mechanism, but there are no further links provided, even though there could be several:

So in short: My ask is more linking between related topics and don’t touch the ordering of the reference pages :slight_smile:

PS: You guys have been great with incorporating feedback from the feedback buttons on the documentation, consider advertising this more :slight_smile:
Edit: Feedback form is actually hidden behind the star rating system, maybe consider making that a separate button.


Thanks for your input @tbinna and appreciate your feedback!

And thanks @tobitheo for your input and valuable feedback. I’ll pass it on to the team.

1 Like

This topic was automatically closed after 8 days. New replies are no longer allowed.