Developing for the unknown lavacon

Developing for the UnknownFuture-Proofing Our Work and Jobs, and Introducing…

Who Am I?

Neil Perlin - Hyper/Word Services.– Internationally recognized content consultant.– Help clients create effective, efficient, flexible

content in anything from hard-copy to mobile.– STC’s lead W3C rep – ’02 – ‘05.– Certified – Flare, Mimic, Viziapps, RoboHelp

in process of renewal.

The Problem… In the past, technical change was unexpected. Today, we know it’s coming, just not the details. Content must be efficiently extensible,

including to changes that don’t yet exist or are dissimilar.

This means we can no longer:– Violate syntax and hack code to be cool.– Exploit tool peculiarities to take shortcuts.– Not understand the future.

The Solution Consider the future, even if unknown. By setting and following standards for:

– Philosophy.– Programming.– Methodologies and procedures.– Strategic business support.

Philosophy

Philosophy Remember our main competitor…

Think web, web-side access, multi-device, SEO.

– Local formats fading in a web-oriented world. Think open source, standards compliance. Keep up.

Programming

In General Automate everything possible.

– But never fully trust an automated process. Follow standards and best practices. Use tools properly for future compatibility. Learn about your outputs, tools, technologies. Use styles and style sheets for anything you can.

CSS Recommendations KISS and document it, esp any unusual features.

– Don’t assume your successors will understand them. Use CSSs for char styles as well as paras, other.

– Supported by Flare, RH, others…» To avoid local

formatting, hide text formatting toolbar and use style pod/pane.

CSS (cont’d) Give custom styles unambiguous names. Review CSSs often to eliminate “barnacles”.

– Like H1, head1, and heading1 styles. Don’t use multiple CSSs on the same topics –

elegant but potentially confusing. Validate CSSs for adherence to W3C syntax.

– Try http://jigsaw.w3.org/css-validator.

Validation Example For example, this page:

Validation Example Gives this result from the Jigsaw validator – the

question is whether these errors matter.

CSS (cont’d) Check the browsers your apps use and see what

CSS settings they support correctly.– www.webdevout.net/browser-support-css

CSS (cont’d) Switch from absolute to relative style size units. Vital for extensible single sourcing.

– %, Ems, Exes vs. points.» % and Ems resizable by browsers, Exes resizable

but not well supported, points not resizable.

Why Relative Sizes? Image at absolute width in a

too-narrow space.– Note horiz. scroll bar.

Relative width in same space.– No horiz. scroll bar, width of

50% makes browser show image at 50% of available space – e.g. “relative”.

– In effect, each browser does the formatting for you.

Media Types/Mediums A feature of the W3C’s CSS2 standard.

– See http://www.w3.org/TR/CSS2/media.html– Called “mediums” in Flare.

To define alternate style settings for different outputs within one CSS – easier maintenance.

Consider using media types if you single source to multiple outputs.

Extended in CSS3 to “media queries” that drive “adaptive content”.– And for HTML5, the basis for “hybrid apps”, more.

Local/Inline Hard to update effectively. Hard to import to new formats.

– To eliminate, you may have to:» Look for local formatting in the first topic.» View that formatting code.» Replace the local formatting code

with a CSS style in all your topics in code view.

» Repeat…

Table Styles If your authoring tool allows, create and use

CSSs for tables instead of local formatting. A table CSS is a standard CSS focused on table

styles, so a regular CSS works too.– A table style editor just makes it easier to visually

integrate all the table elements.

Topic Templates Define topic templates to control:

– Structure of material for each type of topic.– Boilerplate content for each type of topic.

Apply the CSS to all templates to automatically give topics the structure plus the styles.– Moves you toward structured authoring even if you

don’t use DITA. Start by defining your information types.

Define Information Types Identify the types of content you create and put

them in a few standard categories.– Concept, task description, reference, process, show-

me, troubleshooting, etc. Try to fit all content into <10 types.

– If some doesn’t fit one of the types, see if:» It could fit if it was modified somewhat.» It calls for a new type.» It’s just weird.

Attributes of Good Templates Limited to your main information types. Simple to use, esp. for non-techie authors, and

needing little or no training. Self-documenting, since instruction sheets get

lost or increase perceived complexity. “Sold” as primarily benefiting users, rather than

the doc group.

A Sample “Task” Template

[delete and type the title][delete and type the intro description]

Date of Applicability

[delete and type the date]

Required Materials

[delete and type the tools and materials list]

and so on…

What’s First – Template or CSS? Elements in templates – heads, lists, etc. – are

the elements you must define in a CSS.– Keep a list of them as you define the templates.– Don’t create custom styles if standard styles will do.

Define Standards Adherence Identify (and enforce) standards to follow, like:

– W3C code compliance.– DOCTYPE declaration in topics to use strict/

standards vs. quirks browser mode.» Determines if browsers render CSS features in

compliance with new, correct standards or still work with older browsers.

– Others…

Methodological, Procedural, and Business Solutions

Methodological In General Before adopting any new methodology, be sure

you understand it and it makes sense for you.– Don’t adopt DITA, structured authoring, topic-based

authoring, Agile, etc. because they’re new and cool.

Procedural In General Develop in-house expertise on formats, tools,

methodologies, etc. “Stay between the lines.”

– Use tools correctly and avoid hacks.– “Standards are portable and hacks aren't”

Avoid hand-coding – slow, quirky, error-prone, narrows your hiring pool.

Design for flexibility.

Business Support the company – Tech comm is often the

only department that rebels at the idea.– Starting to accept the idea of cost-justification, but

that’s not enough.» Pure cost-justification usually = outsourcing.

– Be able to show how tech comm supports company strategy in ways that outsourced doc does not.

Business Get credibility – become a techie. Keep it – be active in product dev. Become a resource for subjects that IT may not

be familiar with, like sound-alike formats.– “WebHelp” = “Web Help”?– “HTML Help” = “HTML help”?– “XHTML” = “XML” = “HTML 5”?

Learn about business – debits, credits, ROI, etc. And as a teaser for my next session…

Hyper/Word Services Offers…

Training • Consulting • DevelopmentFlare • RoboHelpViziapps • Flare/RoboHelp Mobile XMLSingle sourcing • Structured authoring

Thank you... Questions?

Hyper/Word Services978-657-5464

nperlin@concentric.netwww.hyperword.com