An Overview of TR1

Authoring Challenges in a
Multiplatform World
Scott Meyers, Ph.D.
Software Development Consultant
smeyers@aristeia.com
http://www.aristeia.com/
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Voice: 503/638-6028
Fax: 503/638-6614
Copyrighted material, all rights reserved.
Last Revised: 1/27/09
What do I Know?
1992 1996 1998
Monochrome books:
Wrote, created
diagrams, indexed,
typeset, wrote bcc.
Monochrome
books: Co-wrote.
Monochrome
books: Series
editor.
2002Adaptation for PDF:
Designed,
supervised.
2008
1995 1996
1996
2001 2005
Adaptation for
HTML on CD:
Designed,
supervised, wrote
new content.
Two-color books:
Wrote, created
diagrams, indexed,
typeset, wrote bcc.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
2008 2008
Multi-platform book:
Writing, designing,
agonizing.
2010?
Monochrome and
multi-color articles
for print and web:
Wrote, created
diagrams. 1983Copyrighted material, all rights reserved.
Slide 2
The Vision and Why Authors Matter
Printed book
What's in here…
Computer screen
Portable electronic
book reader
Manuscript
from author
…affects how easy and
effective these transitions are
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Multipurpose
portable device
Audio device
Copyrighted material, all rights reserved.
Slide 3
The Goal
Platform-agnostic
manuscript from
author.
Facilitates:
 Exploitation of
platforms' strengths
and capabilities.
 Accommodation of
their weaknesses.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 4
Some Platform Variations
Color?
Display
Size
Diagrams,
Graphs,
Tables?
PageBased?
Dynamic? Personalizable?
Rarely
Medium
Yes
Yes
No
Maybe
with
POD
Typically
Big
Yes
Maybe
Yes
In
concept
Maybe
Medium
Maybe
Maybe
Yes
In
concept
Typically
Small
Yes, but
small
Maybe
Yes
In
concept
Maybe
Typically
small
Maybe
No
No
In
concept
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 5
What Works Poorly
Conventional
manuscript
from author
Authors design/write books that are:
 Static
 Monochrome
 Page-based
 Visible
Other formats suffer.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 6
What may go in a Platform-Agnostic Manuscript?
Anything that “works” in printed form.
The usual suspects:
 Text, diagrams, tables, photographs, etc.
In addition:
 Color
 Video/Animations
 Expository
animations: OK.
 Talking Heads: typically OK.
 Other: often not.
 Audio
 “Speaking
Voices”: typically OK.
 Songs: often OK.
 Music: typically not.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 7
Challenge: Adopting New Tools
New expository tools:
 Color, video/animations, audio
Authors need to learn:
 What works where? Why?
 What doesn’t? Why not?
As true for novelists as for technical writers.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 8
Adopting New Tools
New software tools to create/capture/edit:
 Video/animations
 Audio/video files and streams
 Color application/manipulation
 Capability-dependent content and
formatting
The more authors do themselves, the more
expertise they’ll need.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 9
Challenge: Capability-Dependent Content
TTS does a decent job on prose†:
In the table immediately below, you can see how the cat_family
groupings have performed (total units) both by quarter and yearly
results.
Tables not so much†:
Graphs, diagrams, charts, etc., are similarly troublesome.
† From
“State of the Computer Book Market, Part 2: The Technologies,” Mike
Hendrickson, O’Reilly Radar, February 22, 2008,
http://radar.oreilly.com/2008/02/state-of-the-computer-book-mar-20.html.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 10
Capability-Dependent Content
Authors should provide capability-dependent content when
appropriate, e.g., when
 Only part of a table is really important and
 The output device has a small or nonexistent display:
If such objects are not optimized away, Table 1
demonstrates that their size could be significant
(up to many thousands of bytes per feature set),
an artifact of the use of virtual inheritance in
the current implementation.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 11
Challenge: Capability-Dependent Formatting
Authors should provide capability-dependent formatting when
appropriate, e.g., when
 Color most effectively communicates something, but
 Some target platforms lack color.
void g(MakeFeatures<tepsafe>::type features)
{
int xVal, yVal;
...
f(xVal, yVal, features);
...
}
void g(MakeFeatures<tepsafe>::type features)
{
int xVal, yVal;
...
f(xVal, yVal, features);
...
}
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 12
Capability-Dependent Formatting
The more colors, the less practical to use line styles, etc.†:
† Figure
8-12 from Thomas Erl, SOA Principles of Service Design, Prentice Hall, 2008.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 13
Aside: Personalized Formatting
Conditional formatting allows per-reader “POD” formatting. Uses:
 Gratuitous personalization :-)
 Effective color combinations for color-blind readers.
 Natural color combinations for different readerships:
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 14
Challenge: Cross References and Links
References to page numbers are problematic:
 Not all platforms are page-based.
 John
Broughton: “Page numbering (hardcopy has page
numbers, a wiki does not) was particularly problematical.”
 Different platforms may have different page breaks.
 Inhibits
communication among readers on different platforms.
Authors should minimize references to page numbers.
Number paragraphs instead?
 Similar to legal codes.
 The Iliad and The Odyssey use book/line.
 The Bible uses book/chapter/verse.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 15
Cross References and Links
References to platform-dependent descriptors are problematic:
 “…the photo in the upper right…”
 “…the diagram on the facing page…”
 “…the red line in the graph…”
Authors should use capability-dependent content instead.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 16
Cross References and Links
References/links truly helpful only when referents are present.
 URLs largely useless off-line.
 “Old” URLs often close to useless anyway.
 “We’ve
reorganized our site…”
 Internal xrefs inhibit partial book sales:
 E.g.,
chapters, recipes.
 “Continuing with the example of Chapter 2…”
 But xrefs and links are useful!
Create “smart” references/links that (optionally) appear only
when referent is available?
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 17
The Role of Publishers
 Experiment
 Encourage
thinking beyond “black text on
white pages.”
 Learn what works (or doesn’t) where –
and why.
 Collect Experience
 Across
authors, genres, “consumerships.”
 Disseminate Information
 Share
results with authors.
 Create guidelines, templates, software
recommendations and quick-starts, etc.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 18
Summary
 Effective multiplatform publication requires author cooperation.
 Designing/writing for print and “porting” to other platforms is a
poor approach.
 Specific challenges include:
 Adoption
of new expository and software tools.
 Expression of capability-dependent content.
 Application of capability-dependent formatting.
 Specification of cross-references and links.
 Publishers should experiment, collect experience, and
disseminate the lessons they learn.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 19
Further Information
“The Fastware Project,” Scott Meyers,
Blog, http://fastwareproject.blogspot.com/.
 Entries for November-December 2008
are most relevant.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 20
Roundtable Tonight
7:30 PM, Broadway North (6th Floor)
Topics:
 Everything in this talk.
 Facilitating community:
 How
book content can foster
post-publication discussion.
 Revision issues:
 Automated
builds.
 Offer readers deltas, older versions?
 Anything else that comes up.
Scott Meyers, Software Development Consultant
http://www.aristeia.com/
Copyrighted material, all rights reserved.
Slide 21