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:
You will be asked to complete a task and presented with a list of links.
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.
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: https://diataxis.fr/. 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
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.
note how there is not much else about external authentication in the Platform Concepts
So in short: My ask is more linking between related topics and don’t touch the ordering of the reference pages
PS: You guys have been great with incorporating feedback from the feedback buttons on the documentation, consider advertising this more
Edit: Feedback form is actually hidden behind the star rating system, maybe consider making that a separate button.
but not to the remotes or the common issues with external authentication