TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Yes, the page is where it's at. Google returns pages, not sites. Often we
don't even notice which site we are on when we read a page.
The New York Times built its online edition around a front page, just like
its paper version. They found that no one went there. Instead, they arrived
at inside pages directly. I read a fair number of NYT stories, but I get to
them through Flipboard, Google Now, and Google Play Newsstand. So I read a
lot of their pages, but I never read their site.
That's definitely what I mean when I say that Every Page is Page One. That
does not necessarily mean the abandonment of any form of top down
navigation. It may still have its uses, especially in smaller information
sets. But it should be a secondary concern. The primary focus should be on
making every page work as page one. In particular, no page should be written
in a way that assumes it was reached from a TOC or by pressing a "Next"
So yes, you lime scaling example is just what I am talking about. How do you
write the perfect page? Well, I wrote a book about that, Every Page is Page
One: Topic-based Writing for Technical Communication and the Web
(http://xmlpress.net/publications/eppo/). The book outlines seven principles
of Every Page is Page One design, but if you want the capsule version it is
maybe this: a perfect page is self-contained, has a single limited purpose,
establishes its context, follows a consistent pattern, and links richly to
related topics. (That is basically five of the seven principles.) The
linking is important, because in what I call a bottom-up information
architecture, readers navigate through content, not to content. (Think about
how you move through Wikipedia or YouTube or Amazon.)
I believe that patterns are the key to successful topic design (which ties
this back a bit to the original question). The Web has become an engine for
refining and surfacing successful information patterns. (Look at how much
patterns dominate content on a similar subject on Wikipedia.) We are not
restricted to surveying our own readers on information design. We can look
for the most successful patterns in our field and similar fields and emulate
DITA, unfortunately, is not particularly good at EPPO (though that does not
mean you cannot do EPO with DITA). The two main problems are that DITA's
highly reductive content model does not produce good EPPO topics, and that
its use of maps as the principle form or organization, combined with how
expensive it is to manage links in DITA, favor a top-down rather than
bottom-up architecture. We should note that DITA is usually sold for its
reuse capabilities -- a content management feature -- rather than as a means
for revolutionizing information design. Design for reusability tends to be
the focus of any content redesign in a DITA environment.
The most EPPO-friendly tools out there today are wikis. I am working on
developing a system for structured writing with a bottom up architecture,
which I call SPFE (http://SPFE.info).
From: Janoff, Steven [mailto:Steven -dot- Janoff -at- hologic -dot- com]
Sent: Monday, January 11, 2016 11:51 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com; mbaker -at- analecta -dot- com
Subject: RE: Seeking Online Help Surveys Advice
So you're saying, Mark, that the page itself is where it's at. A single
page is paramount. (Typically web page.)
You want the single page that the person lands on to convey a full scope of
information that they're looking for (somewhat to the granularity they're
looking for), and then for additional information they can follow
appropriate links that sort of branch out to neighboring subjects, or parent
subjects, or child subjects.
So you can't worry about organization or progression through some kind of
continuum, you can only be concerned with the single page itself. (I'm
guessing that's what you ultimately mean when you say that every page is
So if I want information on a particular task -- let's take something
mundane like how to clean limescaling from a sink faucet -- I want to land
on a page that gives me enough conceptual background to know what I'm doing,
and then the specific steps to accomplish the task (and have a bright and
shiny faucet once again!). And if I need supplemental information, I would
ideally be able to find that in links that appear on that same page.
But presumably I would not have to leave that page if it has exactly what
I'm looking for to accomplish that task.
By the way, do you think that something like DITA accomplishes this? Or any
form of structured writing?
I see what you mean, though, by saying that at this stage of our progression
as users of technology, a book is no longer important, nor is a help system.
It is the single page that is king, in a certain sense.
So the holy grail is to write the perfect or ideal single page for the topic
you're dealing with. (Page and topic might be synonymous here since you
would typically scroll down a web page to read what you need, as with most
So the question to me is, how do you write the perfect page? What's in it,
and what's not in it?
You might have spelled this out over time on your blog, but it'd be great if
you could sum it up for us here.
Thanks for a provocative post.
PS - Another thought is, what kind of organization would you use for such a
system, if any at all. Is it just a loose collection of pages only linked
together by hyperlinks? Would there be a hierarchy of pages? Or would it
On Monday, January 11, 2016 6:28 PM, mbaker -at- analecta -dot- com wrote:
I agree with everything Peter says.
But it gets worse.
First, you are only reaching the people who are actually using your help.
The people you should probably care about most are the ones that don't. Most
of us can no longer assume that we have a captive audience.
Second, what users want is to type their question into a search box and have
the right answer pop up. If a page shows up that looks like it might be
relevant, they will follow links from that page as long as they feel the
information scent is getting stronger. That's pretty much it. They no longer
accept that they should have to learn how your content is organized or spend
any time learning their way around your documentation set.
They would rather the search box be Google. If it is not, they will probably
try Google first. If they do try your help first, they will soon get
frustrated and go to Google if they don't find an answer quickly. They will
not be conscious of using an organized help system. They will see a page or
a set of pages turned up by search or by following links.
They don't know or care about help system design, formats, or organization.
It has been demonstrated that when you ask people what format they would
like a manual in, they tend to say PDF, but they rarely actually look at
PDFs when they are provided if there is searchable online help available. My
guess is that what they mean when they ask for PDF is, "Oh God, don't give
me paper," and that they probably don't think of the help pages they
actually use as being a manual at all.
At best you will get some schoolbook answer about how they think books are
supposed to be organized or how they want you to think they do research.
Censorious pundits keep telling people their research habits are shameful,
so they don't want to admit to them. (Though, information foraging theory
would suggest that their habits may actually be optimal.) Thus they won't
often say, "Oh I just Google for it" because they think that will make them
look bad or make you feel bad about all the effort you are putting into
organization they don't use. But for the most part, they just Google for it.
So your survey is based on a false premise. Users don't use your help
system. They use the first search box they can find and they glance at some
of the pages returned by search hoping to pick up an information scent they
What matters, therefore, is not how your help system is organized, but how
well you pages work when people come to them like this, and how well linked
they are so they can follow the information scent were it leads.
Author: Every Page is Page One: Topic-based Writing for Technical
Communication and the Web
From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of Peter Neilson
Sent: Monday, January 11, 2016 6:41 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Seeking Online Help Surveys Advice
People using online help want a solution to an immediate problem. They do
NOT want, when looking for the help, to be presented with anything about a
survey. I normally send those surveys to my own version of /dev/null
(formerly the circular file).
The people who answer the surveys have already self-selected themselves to
be the ones who don't need crucial answers NOW.
Additionally, most surveys are badly constructed, and have at least one of
- Ask for rating on a scale of 1 to 10 (or 0 to 9) instead of "bad - don't
care - good".
- Present the perpetrator of the survey with numeric results that are really
- Annoy people with mandatory selections.
- Annoy people with selections like "needs improvement - okay - great"
when "horrid" should have been one of the choices.
- Fail to collect lengthy, written responses.
- Fail to collect a critique of the survey itself.
- Seem to pretend a preservation of anonymity.
- Indicate in flashing neon that the questions were never tested on a naive
There are plenty of other faults. Those are just some.
Try to make sure your survey is harmless, or at least mostly harmless.
On Mon, 11 Jan 2016 15:37:16 -0500, David Renn <daverenn08 -at- gmail -dot- com>
> Hi Whirlers,
> My company is working to put together a set of survey questions to
> gather information about our online help users.
> The general premise is to simply find out more about our users. That
> is, who they are, what information they typically look for, what sort
> of format/organization they prefer online help content to be in, what
> they think of our current help, etc, etc.
> For those of you who have experience with this, do you have any
> stories to share about your experience or general advice? Are there
> any particular questions you think are must-haves to include in
> surveys like this? Is there a sort of tone or way of framing questions
> that yield the most helpful results? Overall, what advice do you have
> that would potentially get the best information to us provide the most
> relevant, meaningful, direct, and user-friendly help content?
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com