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.

1. Usable Documentation
BY KEVIN BRAUN

2. Email:
kevin@brauninteractive.com
Twitter:
@humanforum
KEVIN BRAUN

4. 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

5. 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

6. 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

7. 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

8. 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

9. 1. No Association to Business Goals
CONTEXT 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?

10. 2. Assumes Knowledge the
Reader Doesn’t Have
DEVELOPERS 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

11. 3. Hard to Find / Unsure if it’s current
IT 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.

12. Hard to Read or Comprehend
NO 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.

13. Not Enough Detail
THIS CAN BE BROKEN DOWN ALSO…
The Zero and Many Case
Tabular Data Interactions
Target System Profiles, Resolutions, and
Breakpoints
System Messaging
Many more…

14. Not Enough Detail
THE 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?

15. Not Enough Detail
THE 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?

16. Not Enough Detail
THE 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?

17. Not Enough Detail
TABULAR 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

18. Not Enough Detail
TARGET SYSTEM PROFILES,
RESOLUTIONS, AND BREAKPOINTS
On 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/

19. Not Enough Detail
SYSTEM MESSAGING
Not 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

20. 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
Thanks for stopping by!