search

wet-boew / wet-boew-styleguide

A style guide for the Web Experience Toolkit.
http://wet-boew.github.io/wet-boew-styleguide/index-en.html
36 stars 32 forks source link

Existing style guide resources #2

Open laurawesley opened 10 years ago

laurawesley commented 10 years ago

This repo has the existing WxT 3.1 style guide in it. We need to update it for WxT4.0, review it against usability and accessibility heuristics as well as any test results AND add what's missing.

UXWG had started a GC style guide (internal link) but the timing wasn't right. The project outline, names of interested parties, Content presentation guidance (internal link) including the section on usability (internal link) may still be useful. Departmental style guides (internal link) for ideas & comparisons are also listed on GCPEDIA.

External style guides we love:

Other resources that we love:

Writing resources on GCPEDIA:

Related issues discussing styles, documentation, formatting etc: https://github.com/wet-boew/wet-boew/issues/1077 - oldest discussion about WxT documentation https://github.com/wet-boew/wet-boew/issues/1918 - using KSS for CSS documentation / living style guide https://github.com/wet-boew/wet-boew/issues/1275 - WxT4.0 planning thread https://github.com/wet-boew/wet-boew/issues/2813 - WxT website IA planning

Supposedly, there is some old thing here but I can't access it on my antiquated browser (or it may be a broken link, not sure).

@jeresiv @cfarquharson @MaryBethBaker @sagecram et al

DTardioli commented 10 years ago

Good resources, thanks Laura. We're developing an Intranet Style guide, I will share the outline here.

thatVargas commented 10 years ago

I like the content, but not the layout. It's clean but cumberson in that there is a lot of content in there. Can I help with that?

cfarquharson commented 10 years ago

@laurawesley I'm a bit confused. Wouldn't a new style guide rework the whole IA for WET in the menu menu. Right now it's "WET Project || Implement WET || Contribute to WET".

Would the style guide not be constructed right into the IA...something like: "About WET || Base CSS || CSS components || JavaScript and polyfills || Writing and formatting || Themes and variants || Contribute"

Personally I would like to see an item on "Accessibility" as well, as there is so much already documented in WET but it's under weird headings like "Optimal content examples" http://wet-boew.github.io/wet-boew/demos/opt-cont/index-en.html

So something like: "About WET || Base CSS || CSS components || JavaScript and polyfills || Writing and formatting || Accessibility || Themes and variants || Contribute" would allow us to get users to all the things about WET, but this is a much bigger (and better, in my opinion) approach. So it's more that just a style guide. It's a revamp of the IA for WET.

This has been a long standing idea stemming from issue https://github.com/wet-boew/wet-boew/issues/1077 where @nschonni @CalvinRodo @naptash @sboots wanted an IA change as the current WET approach made it harder to find info.

One we decide on that, it's easy to put content in. All the Bootstrap content would go into "Base CSS" and "CSS components". The scripts would go into "JavaScripts and polyfills. All the accessibility tools and documentation would go into "Accessibility". The writing guides can be merged and put into "Writing and formatting" etc.

Thoughts anyone? @elmolinero @DTardioli @jeresiv @MaryBethBaker @sagecram

DTardioli commented 10 years ago

@cfarquharson a Web Style Guide's key role is to ensure a consistent user experience that goes beyond the look. We are currently working on an Intranet Web Style Guide - I've added the table of contents below. Our style guide takes into account that an IA has been completed and that the "look" has been aligned with the WET template.

Writing for the Web (Plain Language, Scannable Text, Write Short, Concise Sentences, Maximum Word and Sentence Count, Active Voice vs. Passive Voice)

Writing Types (Information, Procedural, Tip/Note)

Writing Content (Define Your Users, Define the User Tasks, Define the Information Users Need)

Style (Use Complete Words - not Abbreviations, Acronyms and Initialisms, Capitalization/ Ampersands, Italics, Underline, Bold, Numbers, Bulleted lists, Procedures/steps for software or GUI tasks, User input, Code snippets, Spelling out characters, Indents, Terminology/Spelling

Layout (Templates, Colours, Fonts, Logos, Sidebar Information, Icons, File Name conventions, Allowed Characters, Language Use in File Names)

Descriptive Names (Top of Page Link, Buttons)

Some references http://www.creativebloq.com/design/create-website-style-guide-6123030 http://www.rcip-chin.gc.ca/sgc-cms/nouvelles-news/anglais-english/?p=6999 http://www.ieee.org/about/webteam/styleguide/index.html http://www.ic.gc.ca/eic/site/pt-te.nsf/eng/00476.html http://en.wikipedia.org/wiki/Wikipedia%3AManual_of_Style

cfarquharson commented 10 years ago

@DTardioli from what I can see from your comment above, is your intranet Style guide focusing mainly on writing? Cuz I agree, that from a content provider stance, we need all of that writing info covered off, but from a developer stance, we also need to address all the scripts and visual design that WET allows for.

I'm not sure where I see the visual side of WET spoken to in your comment above...is it all in the 'Layout' section? If so, we need to be careful about putting it all into a single label as the inclusion of Bootstrap: http://getbootstrap.com/ etc means that there are a ton of CSS classes and most have little to do with 'layout'....for example, the choices are making a link look like a button, are not layout decisions. Same goes for styling an image with a border or making an image a circle...same goes for making a list unstyled versus a list-group etc etc. None of these are layout design choices. In you comment, you mention that icons, colours and fonts are part of layout and I'm not sure that these are "Layout" either.

I would like the ability to contain writing away from the visuals (as you have done) but I think they are two halves of the same coin and should get equal (or at least similar) billing. Writing styles shouldn't be over-highlighted if it means that CSS, JavaScript/Polyfills etc get batched together under a single section.

I think one thing we need to do it figure out the scope of the style guide and then allocate resources to that. The writing section is certainly one huge area, the visuals are another. I'm happy to tackle the visuals...the writing is not my strength (I think a comma belongs everywhere ;).

What does everyone think this style guide should include? I see the following (at minimum):

Writing (per @DTardioli)

Layout

CSS

JavaScript and polyfills

Themes and variants

pcwsmith commented 10 years ago

Personally I'd separate out the writing from the design, make 'em two guides. two sides of the same coin, getting equal but distinct treatment. Call one a style guide and the other a design guide. Or whatever, but give them different names.

DTardioli commented 10 years ago

@pcwsmith @cfarquharson @elmolinero IEEE.org [http://www.ieee.org/about/webteam/styleguide/index.html] has their style guide broken down into pretty sections: (I meant pretty good)

IEEE Web Site Requirements and Style Guide

I still feel that the IEEE guide is a little thin, doesn't go far enough for our purposes.

From the technical side, a style guide goal should be there to provide guidance on which button/widget/plugin to use for which specific situation. There can't be open access to all bootstrap options that leaves decisions like which colour button or icon to use, how big to make it and when to use it up to whoever happens to be coding that day.

rubinahaddad commented 10 years ago

I agree to keep the writing guide and design guide separate as they are their own two entities.

For your last comment Chad, those categories were pretty much what I was thinking. I was thinking of merging the categories seen in BBC's GEL guide, and what we have on WET.

For the categories on IEEE i find them a bit confusing. Isn't navigation part of the layout, and isn't linking and images part of content?

After doing some research on design style guides, and who the users are it seems like users generally do not read a style guide from beginning to end. They are looking for something specific whether it is looking for a certain pattern or finding all the possible layout options for their page.

I came up with this list of what to include in the style guide - it’s a first draft, but I was trying to think of everything a user would want (based on Laura's personas).

http://www.gcpedia.gc.ca/wiki/File:DesignStyleGuide_v1.docx

Everyone’s input would be appreciated!

Thanks!

jeresiv commented 10 years ago

@rubinahaddad

If we are trying to engage the community and develop this tool openly lets stay away from gcpedia as not everyone participating will have access to it.

Instead, why not convert your document to HTML, or wiki and post it on this repository. I would be happy to help or show you how to use the tools.

rubinahaddad commented 10 years ago

That would be great @jeresiv thanks! Could you please email me at rubina.haddad@tbs-sct.... ?

DTardioli commented 10 years ago

The design style guide is a good starting point. It pulls together items that are under the Standard on Usability (navigation, priorities, search box, date modified) and WET plugins. My concern is that the design guide will become overloaded with items that should/could be covered under a "template" section.

http://www.smashingmagazine.com/2010/07/21/designing-style-guidelines-for-brands-and-websites/ http://www.cunardguidelines.com/

rubinahaddad commented 10 years ago

Figured out the wiki. Here it is: https://github.com/wet-boew/wet-boew-styleguide/wiki/Design-Style-Guide-v.-1

@DTardioli Are you saying there should be a different guide for the template?

DTardioli commented 10 years ago

Not really, some of the items listed are part of the template right out of the box. The style guide should define how to use those items and list the options to ensure a consistent user experience at all levels.

For example, the error pages are pre-built and part of the template. Here is an example of a template 404 with different messaging...

http://www.tpsgc-pwgsc.gc.ca/comm/404 http://www.canada.gc.ca/404 http://www.agr.gc.ca/404 http://www.ic.gc.ca/eic/404 http://www.publicsafety.gc.ca/404 http://www.bst-tsb.gc.ca/404

Might seem like a small item, but considering the web renewal that is taking place, I'm sure there will be a lot of broken links across all levels of GC.

There are also quite a few design components currently in the WET Design Guide that list "Correct Use": http://wet-boew.github.io/wet-boew/demos/guide-design/components-en.html

laurawesley commented 10 years ago

Lots of great ideas and discussion. Thanks for pushing us @jeresiv. Love @DTardioli 's description of the style guide - "Web Style Guide's key role is to ensure a consistent user experience that goes beyond the look." Most of the topics you're including in your intranet guide are in the writing guide that is also underway (though nothing in there about usability/accessibility so let's keep that in scope).

We have to be careful not to start with defining the Information Architecture (IA) since we are not our clients. We are overly familiar with the standards, toolkit and how everything has been created and implemented in our own environments.

All of the suggestions for organizing content probably have nuggets of truth in them; we won't know until we test.
I have Optimal Workshop/Treejack. Let's run a test on the proposed IA until we get it right. This guide won't necessarily be part of the WxT website but it could be. Who wants to lead the testing?

Also agree that users of the guide won't be reading the whole thing every time - they'll be looking for something specific - so all the content needs to be chunked and we'll probably need mulitiple paths to the same content. Some of the content will be useful to technical folks and some people who are not as technical also need to use it.

Our goal is to enable our colleagues to create usable, accessible (useful...) websites. We've identified enough gaps that need to be filled. Let's focus on documenting what people need to know while at the same time figuring out the best way to organize it (and the layout) of it.

nschonni commented 10 years ago

We are also using the jQuery Style Guide for the v4 coding standards.

MaryBethBaker commented 10 years ago

I echo @laurawesley's comment about getting started filling in the blanks and coming back to the overarching structure a bit later. The Designing for User Behaviour working group had a basic scaffolding for our design pattern library when we started, and then as we got further into the writing process we modified and edited it to best fit our needs.

Another suggestion, is to do a quick review of the personas for the Wxt audience, since these will come in handy when reviewing your first few drafts and sorting through the specifics. This will help you keep in mind the audience's goals and skill levels. The style guide will enable a disciplinary diverse audience and so the more who test out the drafts and comment back on github, the more usable it will be.

rubinahaddad commented 10 years ago

Thanks everyone for all the great input! I was hoping we could test it - so very glad we have some tools! What if we were to have an open card sort as well (OptimalSort) ?

cfarquharson commented 10 years ago

@laurawesley @MaryBethBaker The reason I'm looking for IA is not because I want to hammer down exact labelling at thie time, but I NEED to understand the scope of this. A 'style guide' is not universally the same to everyone and sometimes it includes writing, sometimes not. I've seen a ton of style guides that don't cover off any CSS or JS and are all about branding and corp stuff (i.e. all the university style guides).

I think we need to define what our style guide contains and as others have pointed out, maybe the end product separates out 'design' from 'writing' but that's not what I'm looking to do now.... I just need to know that we are all on the same page.

For me, this product will cover off:

Depending on the scope, it could also cover off:

Once we know the scope, we can start to pair up with others who have a similar interest and tackle that section. I won't touch 'writing' with 10-foot pole cuz I'm not the guy you want for that.

I worked with Ross Kippen at CRA to create the WET3 Design Guide: http://wet-boew.github.io/wet-boew-styleguide/components-en.html so I'm keen to get one for WET 4. I was easy to do because it wasn't collaberative, it was just CRA's work pushed out on GC. Now that we are collaberative we need to know what we are working towards so we can each work on something. FYI, the WET3 Design guide was done in just a few days and posted live. It can more that fast when there is a focus on the end goal.

If we can get a spotlight one what we want it covered, then I can find others who want to tackle the CSS / JS stuff with me. Everyone can tackle different areas and then we can blast through this.

DTardioli commented 10 years ago

@rubinahaddad @cfarquharson @laurawesley How does this breakdown look?

Web Content Style Guide The Intranet Web Content Style Guide we are developing would hopefully ensure consistency and quality from content providers. Anything dealing with colour, icons, positioning falls into a design/layout style guide - most of which is covered through the use of a WET template.

Design Guide for the Web A Design Guide for the Web is where I see the Technical info that covers coding, image sizes, use of buttons, styles, JS, CSS, HTML. Many of the WET working examples already have a "Use when/Do Not Use When" in the documentation [https://github.com/wet-boew/wet-boew/wiki/Slide-out-Tab]. Similar approach to Graphic Standards Manuals.

User Experience Style Guide. Neither a Web Style Guide nor a Design Guide would be able to deal with specific user experience scenarios when it comes to whether or not the information is going to be useful to a user. The could be covered under a User Experience Style Guide.

There was a good example from Leisa (Gov.uk/UXCamp2013) on what they thought the user wanted versus what the user needed. User testing identified what users really wanted to do.

The UK Gov service design manual [https://www.gov.uk/service-manual] is really their User Experience Style Guide.

These three guides could be in one document. Yes it would be long, but it would be a one-stop shopping solution for creating content for the web.

Bringing it all together The US Department of Energy's EERE Office has a pretty good model [https://www1.eere.energy.gov/communicationstandards/] but is very thin on User Experience/Usability Guidance [https://www1.eere.energy.gov/communicationstandards/analysis_usability.html].

Example of Graphics Standards manuals http://www.bcit.ca/files/pdf/bcit_gsm1.pdf http://www.gov.nl.ca/brand/GSM%20Brand%20Standards.pdf http://www.bcit.ca/files/pdf/bcit_gsm1.pdf http://www.ryerson.ca/content/dam/branding/guidelines/manual/Ryerson_University_Graphic_Standards_Manual.pdf http://biblioottawalibrary.ca/sites/default/files/logo/IdentityStandards03.pdf

Federal Identify Program Manual (http://www.tbs-sct.gc.ca/fip-pcim/man_pdfs-eng.asp).

Hope this helps.

jeresiv commented 10 years ago

I have added a new and old directory to the repository. The new directory has the dist folder for WxT4, and old has the dist for WxT3.

Now you can be begin developing content with the latest version. Laurent and I also set up travis to automatically push changes to the gh-pages branch, which means that you can see contributions live as you make them.

rubinahaddad commented 10 years ago

Thanks @jeresiv for setting up the directories, and everyone for the great examples!

So there are a lot of great examples, and ways to organize the style guide, and I think all of us have our own thinking on how it should be organized which is where the testing will come in handy.

I think we should do an open card sort so everyone can choose their own categories. Any thoughts/objections on that?

I created another wiki page where I have removed the categories (and detailed sections), so if everyone can look at it, and add any items they think are missing, and then we can card sort based on those items.

https://github.com/wet-boew/wet-boew-styleguide/wiki/Design-style-guide---no-categories

Please keep in mind that this list is based on a style guide for Canada.ca. A general WET one will be implemented, but I don’t want to tackle all of them at the same time (unless somebody else would like to focus on that now?)

Thanks again!

laurawesley commented 10 years ago

We probably don't need more examples, but I found one anyway: http://www.theuxbookmark.com/2010/08/interaction-design/a-monster-list-of-ui-guidelines-style-guides/

DTardioli commented 10 years ago

@laurawesley One? more like 58 examples. Great resource, thanks Laura.

DTardioli commented 10 years ago

@laurawesley @cfarquharson @rubinahaddad I added our content style style into the wiki https://github.com/wet-boew/wet-boew-styleguide/wiki page

rubinahaddad commented 10 years ago

Thanks @DTardioli i just saw the writing style guide – a great base! I thought you had added the priority components section too (It was Thomas) so ignore my other comment. 

laurawesley commented 10 years ago

Looks like some confusion around the term "IA" IA = how all the content is organized. Whereas, I think what @cfarquharson is asking for is a list of all the topics so we can see the scope of everything and just get 'er done.

Agree focus here should just be documenting everything that needs to be documented, then we can sort, test, organize, fill in the blanks. The trick here will be creating each section so it is self-contained so that regardless of where it ends up, it will still be useful/understandable. Let's not worry about how it will all be organized until we have the content.

@DTardioli @cfarquharson Love what you've got so far!

I will work with @rubinahaddad @thomasgohard to make sure questions surfacing from the heuristic reviews get tested in February.

@elmolinero and @neoInsight will be interested in the progress on this thread.