Embed Size (px)
DESCRIPTION
Creating documentation for designers and developers that is actually usable...treating project team members like "end users" of UX deliverables and hopefully creating better products because of it.
Citation preview
Usable DocumentationBY KEVIN BRAUN
Documentation can fail to be awesome for a large number of reasons. THAT SAID, MOST PROBLEMS BOIL DOWN TO THESE 5 HIGH LEVEL ISSUES:
1. No association to high level business goals
2. Assumes knowledge the reader doesn’t have
3. Hard to find / unsure if it’s the most current
4. Hard to read / comprehend
5. Not Enough Detail
Documentation can fail to be awesome for a large number of reasons.
1. No association to high level business goals
2. Assumes knowledge the reader doesn’t have
3. Hard to find / unsure if it’s the most current
4. Hard to read / comprehend
5. Not Enough Detail
THAT SAID, MOST PROBLEMS BOIL DOWN TO THESE 5 HIGH LEVEL ISSUES:
Documentation can fail to be awesome for a large number of reasons.
1. No association to high level business goals
2. Assumes knowledge the reader doesn’t have
3. Hard to find / unsure if it’s the most current
4. Hard to read / comprehend
5. Not Enough Detail
THAT SAID, MOST PROBLEMS BOIL DOWN TO THESE 5 HIGH LEVEL ISSUES:
Documentation can fail to be awesome for a large number of reasons.
1. No association to high level business goals
2. Assumes knowledge the reader doesn’t have
3. Hard to find / unsure if it’s the most current
4. Hard to read / comprehend
5. Not Enough Detail
THAT SAID, MOST PROBLEMS BOIL DOWN TO THESE 5 HIGH LEVEL ISSUES:
Documentation can fail to be awesome for a large number of reasons.
1. No association to high level business goals
2. Assumes knowledge the reader doesn’t have
3. Hard to find / unsure if it’s the most current
4. Hard to read / comprehend
5. Not Enough Detail
THAT SAID, MOST PROBLEMS BOIL DOWN TO THESE 5 HIGH LEVEL ISSUES:
1. No Association to Business GoalsCONTEXT IS KING!
If your team doesn’t know why they are building what they are building they don’t have the context necessary to provide critical feedback or identify additional opportunities for efficiency.
◦ What is the overall business goal?* are we trying to improve top or bottom line?
◦ What is the high level strategy? Are there others?* What’s the plan?
◦ What are the key objectives?* How will we know what level of success we have achieved?
2. Assumes Knowledge the Reader Doesn’t HaveDEVELOPERS KNOW A LOT ABOUT A LOT OF THINGS, BUT NOT EVERYTHING ABOUT EVERYTHING.
◦ Are there specific security (PCI) issues with this effort?
◦ Are there analytics issues?
◦ Are there any special considerations around availability / shipping?
◦ Internationalization?
http://www.peak10.com/cloud/pci-compliant-cloud
3. Hard to Find / Unsure if it’s currentIT DOESN’T MATTER HOW AWESOME YOUR UX IS IF THE DEVELOPERS ARE BUILDING OFF AN OLD VERSION OF THE SPECIFICATION!
◦ Have a secure central location for your developers and clients to access your documentation…email doesn’t count.
◦ Make sure each member has access to the documentation. Have a “sign in” sheet in that directory so you have verification that everyone is in.
◦ Make sure to version and date your documentation so it’s very easy to make sure everyone is on the same page.
Hard to Read or ComprehendNO ONE IS GOING TO READ YOUR DOCUMENTATION LIKE A BOOK… IT NEEDS TO BE SCAN-ABLE!
Visual hierarchy is just as important in your documentation as it is in the system you are designing
◦ Is your font large enough? Ask and your “users” will gladly give you feedback.
◦ Are you using size, color, contrast, spacing, etc. to improve the visual hierarchy?
◦ Are you using grouping, repetition, and consistency to promote scan-ability, readability and comprehension?
◦ All of the above will provide better accessibility as well.
Not Enough DetailTHIS CAN BE BROKEN DOWN ALSO…
The Zero and Many Case
Tabular Data Interactions
Target System Profiles, Resolutions, and Breakpoints
System Messaging
Many more…
Not Enough DetailTHE ZERO AND MANY CASE
Not considering what happens if there is no content of a specific type to display
◦ Do we display a message …possibly with a link to how to add content?
◦ Do we simply collapse the area with no content and assume the user understands?
◦ Do we hold the space for content even though there isn’t any content to display?
Not Enough DetailTHE ZERO AND MANY CASE
Text areas that do not account for much content…or content of the wrong type
◦ If too much does it truncate? If so how many characters…or at what pix dimension etc.?
◦ If too much does it scroll…if so at what size…and standard scroll bar or custom?
◦ What about quantities? Is the limit 99, or 999, or 9999 etc.?
◦ What if someone crams an image in there…does it auto-size to fit, break the layout, or does the system prevent that? If so, how?
Not Enough DetailTHE ZERO AND MANY CASE
Some final examples of this case…
◦ URLs and Email address and other non-breaking text
◦ Pagination…if so what kind
◦ Endless loading / scrolling?
Not Enough DetailTABULAR DATA
How will users interact with the data…
◦ Are the columns sortable? If so all? If not what columns will be?
◦ Is the table layout fixed or fluid?
◦ What happens if the column isn’t wide enough for the data? Tool tips? Abbreviation?
http://uxmovement.com/content/9-design-techniques-for-user-friendly-tables
Not Enough DetailTARGET SYSTEM PROFILES, RESOLUTIONS, AND BREAKPOINTSOn what devices and resolutions does this need to work?
◦ What hardware will be used? And what version(s)?
◦ What is the minimum resolution supported for each device?
◦ Are there target breakpoints? If so how many and what are they?
◦ How should images behave across resolutions? Do they scale, get “re-sourced”, dynamically crop? All of the above?
◦ How should the system display on very large resolutions, centered? Left justified? Is the background image big enough? If not is it designed so it doesn’t matter? http://johnpolacek.github.io/scrolldeck.js/decks/responsive/
Not Enough DetailSYSTEM MESSAGINGNot specifying system messages…what triggers them, where they go, how they are styled etc…
◦ What does the system level error look like and where does it show up?*User entered wrong credentials
◦ What does a line item level error look like?*User entered an invalid email
◦ What does a warning look like?*User has made a selection that may take a while to load
◦ What does general system message look like?*Our system will be down until 2:00pm EST
http://www.telerik.com/kendo-ui/notification
Thanks for stopping by!
To review:
1. Make sure to add a short description of the high level business goals
2. Cover important items like security, analytics and internationalization
3. Make sure it’s easy to find…and easy to see that it’s current
4. Make it easy to read
5. Make sure to cover the details
