Let's Improve the Documentation

[annwa]

Designers are having a hard time keeping the docs up-to date because installing and maintaining a codebase on their computers is quite a bit of overhead just to update some static HTML pages.

We'd like to get the documentation moved to a platform that has less overhead.

We see this as a way to make sure more of the "tribal knowledge" around Canon is documented in a clear and logical way. (Currently there is a lot that is in the hearts and minds of designers but not documented on the web for others to benefit from)

[annwa]

Conversation will be held on slack. Let me know if you need any help getting plugged into that.

[araiford]

Posting undocumented existing patterns here to have something to reference:

• Navigation
• Breadcrumbs
  • ex: Cloud Files navigation
• Voice and Tone
• System Emails
• Login
• Two-Factor Login
• Two-Factor device management
• Reset Password
• Form Validation
• Form Buttons
• Form Submission
• Sub-Process Configurables During Item Creation
  • ex: the Configuration section while creating an AutoScaling group
• Multi-Step Processes
• Wizard Processes
  • ex: BigData Cluster Creation
• Filtering a List by Dates
• Updating a list table item
• Deleting a list table item
• Quick Add a list table Item
  • ex: meta data list table
• Batch actions on items in a list table
• Nested list table rows
• Adding items to the thing you are managing
  • ex: adding nodes to a load balancer
  • ex: adding recipients to a notification plan
• Uploading
• Dates
• Accessibility
• Cascading Selection
  • ex: flavor selector
• Pricing Indication
• Region Selection
• Dropdown Cogs and Buttons
• Iconography
• Displaying Status
• Button and Link Labelling
  • ex: Action versus Navigation
• First-Time Experience
  • Control Panel
  • Product
  • Feature
• Zero-State Tables
• Messaging
  • Inline Banner
  • Growl
• File Browsing
• Charts & Graphs
• Actionable Notifications
  • ex: accepting shared images
• Table Pagination
  • doesn't exist in Canon, but probably should
  • does exist in MyRack
• Linking accounts
  • ex: linking a cloud account to dedicated
  • ex: linking an ObjectRocket account to Cloud
• Ellipses on Action links

[bradgignac]

I'm a bit concerned about items on the list such as login. Why do we need a pattern for login? The only reason I can think of that we need documented patterns for login is that we've failed to build a single login system for Rackspace. If we build that, we no longer need a pattern for it. The shared login system itself becomes the documentation AND implementation for how login should work. Of course, we may have research and other documentation that informs how we build the implementation. However, we don't need a documented patterns that other teams follow when building their login system. Instead, they just use the same one as every other team. I think the same logic applies to 2FA, system emails, password reset, navigation, and linking accounts.

[araiford]

That's a really good point @bradgignac and I think it speaks to the necessity of an internally documented UX library. Purely in existence so that designers can all understand exactly what the design decisions are with a particular interaction. They don't all need to be published publicly, but they do all need to be documented so new peeps can go back and read about established decisions.

[araiford]

BTW - This was a big reason for the kickoff of the New Canon Docs discussion.

[ddunlop]

Is there another area for design decision documentation not related to canon at the moment?

I agree with Brad that we should only have one login implementation. It makes sense to document the decisions that went into that implementation, but I'm not sure that documentation should not be in Canon.

I see the UX library as reusable pieces that can be picked up quickly by a variety of teams, sticking to well thought out patterns should be easy. The library doesn't need to solve every problem. The reasons for decisions doesn't need to be the focus of the documentation but it should be there for when someone is interested.

[annwa]

@ddunlop currently we don't have another place for storing design decision documentation

@bradgignac I'm a little confused because how will people know how to implement a login if there is no record that it exists? This is the problem we are facing with a lot of our undocumented patterns. Often another team will spend quite a bit of time trying to solve a problem only to find out later that another team already spent time solving it.

[bradgignac]

@annwa My point is that no one else should need to implement a login -- we already have too many. If a team is spending time implementing a login page, they are wasting engineering time and creating unnecessary code that needs to be maintained. We should have a single login page for all Rackspace properties maintained by a single team. There still needs to be documentation for patterns. However, the documentation isn't intended to help someone implement a login page. Instead, it is to help designers understand why certain decisions were made. Quoting @araiford's comment above:

Purely in existence so that designers can all understand exactly what the design decisions are with a particular interaction. They don't all need to be published publicly, but they do all need to be documented so new peeps can go back and read about established decisions.

[araiford]

@bradgignac is right on.

Thinking about my experience lately though - I would also throw out there that some teams may not be in a state of integration that allows them to use Rackspace login yet. But they are moving towards integration and do want know how to design their login to be like Rackspace as they move towards full integration.

Then documentation would help - but to @bradgignac's point again - ultimately everyone with a high level of product integration should be using Rackspace login.

To me, the real cutoff line is when a product is ready to integrate with Identity to give their customers Multiple User Logins and Multi-Factor Login. At that point it becomes a REAL, REAL pain to maintain your own login code.

[annwa]

@araiford let's add breadcrumbs to the list... they exist in cloud files

[araiford]

Good point @annwa .