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.
> It is a variable for someone who has to document more than one thing. The
> audience is variable at the project level. If you always write the same
> kind of thing aimed at the same type of audience you can assume a certain
> baseline skillset. But when you write about more than one product, when
> you write for different customers, your audience can and does change.
Are you saying it's variable within a project, or from project to
project? These are two very different things. I agree with the latter
and I disagree with teh notion of the former.
> That's *my* point. And since the nature of the audience changes depending
> on the nature of the product you're documenting, then from project to
> project the audience skill level very definitely is variable.
I don't see where we're in disagreement.
> I already know that. But my boss tells me "make sure it includes
> rock-bottom-level instructions on how to use a mouse because that's what
> the customer wants." Am I supposed to tell him no? On this project I did
> make the argument that it would be inefficient to reinvent the wheel. I
> pointed out that there are already sources that could provide the end
> users the kind of basic information they needed, and that those sources
> were polished to a degree that I could not match with the time and
> resources available to me. And I was told the customer just wanted another
> chapter to the user guide, and to just do it.
That's your call and your company's call. My position is to not do it,
and to ask them to consult with the Legal dept. before deciding. Most
of the time my position "wins". In the cases where it does not "win"
the requirements are modified and the work is documented as a special
service request, and the client is billed for it with an agreement
that additional support for 3rd party technology will not be provided
by our company.
> My point in writing that paragraph was to point out that yes there still
> are people who need to be told what "drag and drop" means.
Fair enough.
> > > The UI designer can put popup tips all over the interface
> > > to explain every feature on it; in most applications, that still does not
> > > tell the user *what to do next*.
> >
> > I think you're missing the point of what a UI designer does.
>
> I'm addressing one aspect of what a UI designer can do. I'm pointing out
> that procedural information can't be built into the UI by using nothing
> but tool tips or similar methods.
But that's not what a UI designer does... Sure, someone could do that,
but it makes no sense to.
> Maybe easier. But the fact is that writing and debugging the actual UI,
> and creating the user guidance on how to do things, is simply too much
> work for one person under normal development schedules. If you have one
> programmer trying to do all those things you have to extend the schedule,
> or, in order to keep to normal schedules, you'll have to divide the
> functions and have multiple people do the project. Yes they'd have to work
> closely together, but there's still simply too many keystrokes to be made
> by one person.
I think you're over-complicating the scenario. This is very feasible
currently, and will be easier with Whidbey. The hardest part about UI
design is the design part. A UI designer does not develop the
underlying functionality. The UI designer's role is to take developed
functionality and deliver it to the user within an easy to use
interface.
> What do you mean by "documents their code"? Every other time I've heard
> that it's meant applying internal comments in the code. That is not
> documentation as I consider it. That's meant as guideposts to other
> programmers to clarify a particular usage of a method, or to locate a
> specific branch point, or something like that. That is definitely not the
> same as trying to write a document that explains the coding rules or the
> design philosophy. And it sure isn't the same as trying to write a
> task-level manual that explains how to work thorugh the UI to perform the
> tasks the end user cares about. To use an analogy, commenting the code is
> like putting a timing mark on the crankshaft pulley - it is not the same
> as writing a tuneup procedure manual. (That analogy probably makes me
> sound like a dinosaur but what the heck. :-)
You miss my analogy. Just as developers comment their code to
communicate to their audience what's what, UI designers document their
work to communicte what's what. Have you ever worked on a UI design
team? There's a hell of a lot of storyboarding that goes on (when it's
done right), and from those storyboards come use cases, task flows,
and procedural steps. It's not uncommon for this information to be
near-publisher ready as-is. The effort to clean it up for distribution
is minimal.
Granted, this isn't the case everywhere, but since we're all
pontificating on purpose, this model fits. A UI designer is a user
advocate, just as the tech writer is. The UI designer and the tech
writer have the same audience and the same raw task at hand: to help
the user get a job done.
> If you mean having the programmers actually write API docs and reference
> manuals and such - I wish I could joke about programmers writing
> documentation. I've been a technical writer for almost two decades and
> every example of programmer-generated documents I've ever seen has been
> painful to read. It doesn't mean they aren't as bright as tech writers -
> it just illustrates what I said about the time requirements. Most
> programmer-generated documents are the way they are because the
> programmers just don't have the time to become good both at code crunching
> and writing.
Right. I think you're running with the wrong ball, dood. ;-)
> This is betting on human nature. There are still a lot of programmers who
> are not good at telling other people how to use the product they turn out,
> or even explaining how it works. And there's still time enough in the day
> to make only so many keystrokes. Considering the fact that the "death
> march" seems to have become the norm in software development, I'm pretty
> sure the realization I wrote about will come fairly soon.
I forget what it is that this realization and "death march" refer to.
So if I respun my argument to something like "technical writers are
well-suited to also be UI designers" would you still be in
disagreement?
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
