The Writing Awesome Documentation session collection

Keith Hays: The 4 essential things you need to do to make your web pages accessible. If your designers have accessible visuals and templates built and you’ve been told “just put the content in,” here’s the basic survival guide to make sure your content complies with Illinois accessibility law.

(First tried in April; rescheduled to May due to technical issues.)

Following on to last month¿s accessibility survival guide, this month¿s presentation takes a more in-depth look at special content types like video and what you¿ll need to do to make sure all your content is available to all your site¿s users. This month¿s topic will require you to have some familiarity with HTML and CSS.

Focus points for upcoming training sessions

Audience targeting: Writing it out of the ballpark
Like Babe Ruth pointing at the outfield, it helps to know who you’re writing to. Integrating usability, accessibility, and good writing principles. Identifying different audiences, getting actual users as readers, using personas as reference points, performing the “grandma check.” Why “common knowledge” is no more common than common sense. Kill the wabbit jargon, kill the wabbit acronyms…

Don’t put off until tomorrow…
For developers: Do documentation throughout the development process, so that you don’t have to remember everything after you’re done and it becomes a big problem

Speed writing from templates
Identifying the common components of the types of documentation you produce most frequently. Faster to build a house with prefabricated walls than from a printout and a pile of lumber. Sample templates for categories of frequently used documentation types – installing software, network assistance, passwords, service status updates, etc.

Images and when and how to use them
How to take good screen shots. How to convert them to web-compatible format. Resizing and converting without making the image blurry. Images as a component of multiple-audience focus – users unfamiliar with a process want images to help them identify components. Admins who’ve done it 50 times before want words to skim through quickly. Single source theory (and sheer lack of time) means nobody wants to write the same installation process twice and keep it up to date in two spots, one with and one without images. CITES’ solution? Image toggles using accesssibility-checked JavaScript – then you can define the view of the page you want, showing all images, no images, or just the steps you want to see.

Single sourcing: write once, read many
The progression from writing multiple versions of a document (web version, print version, poster version) to writing reusable content blocks and manipulating the display methods. XML, RSS, SSI, alphabet soup. Content sources we can share among ourselves more effectively than we currently do – map data, time data, scheduling data, availability/restrictions.

Wikiwikiwikiwikichomp
Confluence tips and tricks. Useful macros. Crowdsourcing and Pac-man.