Atlaskit site - add content back, please?

I know that the Atlassian ecosystem isn’t really the focus of atlaskit anymore (or if Atlassian really wants to invest into the support for atlaskit to be used by external parties). But here’s hoping that somebody out there is listening.

It would be awesome if we could get the old design guidelines back - especially around the components that we have to recreate in order to use Atlassian Connect (cough cough Modal Dialog).

The current design site is really more targeted for the folks that are using Atlaskit and not for “here’s how”. (we really need the here’s how and the reasoning behind things).

/Daniel

7 Likes

Hi Daniel,

Could you clarify what you mean by old design guidelines? We didn’t remove any of the old design guidelines with the redesign. We actually merged design and developer documentation and guidance into a single location. Our new design system documentation site is not targeted for anything or anyone using “Atlaskit” any longer — we’ve actually expanded our audience to designers, developers, content designers, and more. :slight_smile: You can read more about this here: Our new home for Atlassian Design System

Modal dialog usage guidelines are available here: https://atlassian.design/components/modal-dialog/usage

Please let me know if this is not what you are looking for~

Example - Modal Dialog:

The previous guidelines talked about how Cancel link should work and how things should
be ordered etc.

None of that are in the new content.

2 Likes

we’ve actually expanded our audience to designers, developers, content designers, and more.

I think this is actually the main problem. You have lost sight of the one group that probably uses Atlaskit the most, which is the app developers that want to deliver a consistent in-app experience for Cloud and Server apps.

The atlassian.design website is clean, neat and pretty. But it’s not helping out the power users that are catering to our shared customers.

If you want to hear about concrete examples, please bring back the old site and we can show you. I hope you understand that I do not know at heart the content of the old AtlasKit site.

The only thing I do know is that I’m missing a lot of guidance for creating an in-app like experience for my apps that would benefit our mutual customers.

5 Likes

What @remie said. If anyone at the atlassian wants to talk about the different use cases -more than happy to sit down and compare.

The current version is more geared towards internal/current users of atlaskit than the previous version.

I guess I should be good and explain why I’m frustrated.

The previous version had a clear explainer about how the Cancel button should be a link and on the left side etc. (More theory I guess?)

That made it super useful to recreate things outside of atlaskit/aui and make sure that you didn’t stray too far away from adg.

Since there are components that you do have to recreate and can’t use atlaskit in connect for. Please consider bringing those back.

Like I said - more than happy to sit down and talk specifics.

2 Likes

Another one that’s missing btw - Page header. There was a page that discussed the number of buttons in the upper right area.

Things might be there I guess but I doubt it (one of the really nice things of this new site is that it is really easy to find things - and when things aren’t there).

Now all of this might be me misremembering things (I don’t think so though). And with the clear target of design.atlassian.com towards using atlaskit - I really do feel that there’s a large gap of awareness that there are situations where you can’t use atlaskit (especially in connect) and have to recreate things…

2 Likes

never mind - found the page header at https://www.atlassian.design/patterns/page-header/

2 Likes

I think I need to note - I’m not saying that the old site was better etc. It just had content that was less atlaskit specific and getting that stuff back would be awesome.

4 Likes

There used to be some nice style guides for terminology, capitalization, and so forth with examples that I can’t find or are restricted and I can’t access them.

@jsyip , thanks for your guidance, but your statement is not true. In fact, at least 1/2 of the old design guidelines are not present on the new site. The old site remains the only way to find these guidelines.

Some of the omissions in the new site are striking. For instance, although the new site had user guidelines for the “Pagination” component, the new site doesn’t include the “DynamicTable” component, much less the user guidelines for the DynamicTable, a component without which a Pagination component on is an orphan.

Nor does the new site have the “Form” component (a lynchpin of any design system) or that component’s user guidelines. Similarly, it’s missing all layout related components, all date/time related components, and all navigation components.

IMO, @remie hits the nail on the head: the main problem with the new site, along with Atlassian’s decision to disable real-world usage of the source code (a successful yarn install for any of the “public” components hasn’t been possible since 2019) means that Atlaskit no longer serves the more deeply committed app developers and integrators that have spent years working with these components. To this audience, the old site remains the only alternative for documentation. So, if you don’t intend to invest in it, hopefully it won’t follow the path of the Atlaskit source code to non-public access.

Atlaskit used to be a complete solution for, as @remie says, delivering consistent in-app experiences to enterprise customers. With full source and build system built in, it could pass security review and be integrated into an enterprise pipeline. But not any longer.

Hi Jeff, there is a new “Content” section now (for Content Designers audience). Are you referring to the Language and Grammar guidelines? https://atlassian.design/content/language-and-grammar/

Hi @ngault,

@jsyip , thanks for your guidance, but your statement is not true. In fact, at least 1/2 of the old design guidelines are not present on the new site. The old site remains the only way to find these guidelines.

As I mentioned in this post (Our new home for Atlassian Design System), we still have a lot of content to migrate over:

Migration of the remaining 30+ design system components (which still live on Atlaskit for now)

So yes, in your words, “1/2 the old design guidelines are not present on the new site.” and this was intentional as it was not part of our MVP to launch. We are working on migrating the remaining content and components over from the Atlaskit site to the new site.

Thanks,
Jennie

Thank you for recognizing that it’s not the same site. I really appreciate you being open about it.

Now the million dollar question - when will all of the removed content be available?

1 Like

Hi everyone,

I think we are all misunderstanding each other in some way because we are not speaking the same language and using terms differently. I will try to clarify a few terms and provide some history:

Previous documentation sites (ADG + AK)

  • Left: Atlassian Design Guidelines (ADG) — https://www.atlassian.design
  • Right: Atlaskit (AK) — https://atlaskit.atlassian.com

Terms

  • Design guidelines:
    Documentation that contains usage guidance (how to use things), best practices, Do’s/Dont’s, and content (writing) guidance.
  • Developer guidelines:
    Documentation that contains examples, API definitions, code sandbox, prop tables, etc.

History

Atlassian Design Guidelines (ADG)

  • The old atlassian.design website, which was previously home to Atlassian Design Guidelines (ADG).
  • The old ADG site had design guidelines for 27 components. Each of these 27 design guidelines had a button on the upper right of each page, which would link to respective components on the AK documentation site.
  • August 2020: The new atlassian.design website launches, which becomes the new home for Atlassian Design System (ADS).
  • The 27 components with existing design guidelines and corresponding developer guidelines are the first set of components to migrate to the new ADS website (https://atlassian.design/components)
  • We did not remove/sunset/delete any of the design guidelines from the old site, we simply moved them over to their corresponding “Usage” tabs on their relevant component pages.

Atlaskit (AK)

  • There are about 60 design system components on the old Atlaskit website.
  • For the first 27 components that migrated to ADS, there is a redirect from AK in place pointing to the new documentation.
  • There are 30+ design system components remaining that need to be migrated to the new ADS website. To be super clear, these components were not migrated in August 2020 because they actually do not have corresponding design guidelines. They only have developer guidelines (which are still accessible on AK). This means that the component was created and released without design vetting. Our design team needs to do research, and write up new guidelines and best practices for how best to use these components before we can migrate them.

This is why some components have been migrated, and some have not, and why some seem to be missing. Please be patient as our team works on creating new guidelines and content in order to migrate the remaining components.

Why are we moving to one site?

It has been difficult to maintain two separate documentation sites as Atlassian and the design system has evolved over the years. Internally, the Design System Team has changed, which means ownership over parts of the design system has also changed as well. One of the biggest pains for our consumers (internal and external) is the inconsistencies across our two documentation sites, and the sites have became more and more out of sync (also out of sync with our tools). The Design System Team is now aiming to create a better source of truth for all designers, developers, and content designers through a unified destination.

Hope this helped clarify some things in the meantime, please let me know if I can clarify anything else.

Cheers,
Jennie

1 Like

@jsyip , I believe the larger misunderstanding is over the purpose of this “new home for Atlassian Design System”. When you say it’s an MVP, the letter “V” stands for “viable”. But you can see on the board that many existing Atlaskit developers feel the new site is not “viable”, especially in the context of what we had up to Jan 1, 2020. Not only was the previous version “viable”, but it was a mature and robust solution to all of our needs.

  • Previously, we had complete documentation for all components in one place, both design guidelines and example code. Even for the components that are included on your new site, many code examples are missing and most all of the technical documentation seems to have disappeared. There are many open source, public design systems on the web that set an expectation in terms of requiring BOTH ux/ui guidelines AND extensive example code. The old incarnation of your site exceeded the standard, whereas the new incarnation of your site falls short.

  • In terms of actual code, the old site was associated with an open source monorepo where the source for any component was freely available and could be built and tested. The components that you point to in the current site cannot be built or tested (yarn install on any of them fails), which has caused many new developers, like @danielwester, above, to waste time, not to mention frustrating Atlaskit’s long-standing users. It’s not a good look.

It appears that Atlassian is wasting an extraordinary amount of money creating an entirely new site. Why not simply add the design guidelines for the 30 newly documented components to the existing site? That can’t be more than a few hours of work once the content is created.

At the least, why not complete the work on the new site before introducing it and causing all this confusion when the previous version of the site ain’t broke?

Thanks

2 Likes

MVP, as a concept, is fine for shipping a prototype to market to assess traction + appetite. Using it for what should be comprehensive technical reference documentation is, IMO, misguided. Atlassian marketplace developers clearly rely on levels of granularity that need a stronger focus than MVP. Appreciate the transparency from Atlassian via @jsyip, but the developer community need the fine level detail that AtlasKit clearly delivered. Having done stints as a technical writer, I know the challenge you’re trying to pull off, but would it hurt to have them running in parallel during the content migration/optimisation?

4 Likes

So my level of frustration with the state of the atlaskit documentation continues (this being the third or fourth time I’m trying to put my words down here). I’ve been trying to use the @atlaskit/grid component ('cause it’s a pretty easy to implement).

The only documentation on it that mentions it:
https://atlaskit.atlassian.com/packages/design-system/page
https://atlaskit.atlassian.com/examples/design-system/page/nested-grid-example
https://atlaskit.atlassian.com/packages/design-system/page/example/basic-usage

None of those really talks about how to use it - it’s just example code. We’re left to our own devices to figure out what it does (apart from reading the source code). There is a link to what I think was an explanation https://atlassian.design/guidelines/product/components/grid - but that’s gone…

So I’m left with an @atlaskit package that I’ve used before, but is no longer documented…

The current situation makes me start questioning if I really should be using atlaskit in my future projects or perhaps instead finding alternatives and re-theming them. I really want to use atlaskit - but the cost of development with it is increasing.

2 Likes

I was just looking for the format that Atlassian uses when displaying a date, but I can’t seem to find it. Perhaps I’m looking in the wrong place or it’s no longer there. I remember there was design documentation about this at some point in the past.

(sharing it here in case anyone is looking for examples / feedback for improvements)