Moving to ArborText

[gstuckey]

Hi,

Thanks to Paul Nagai for answering my tweet and suggesting I look for answers here. I have a fewquestions. I am very familiar with writing HTML and CSS and I know that many of the principals are the same. However, I ammore familiar with the XML authoring part of the whole XML umbrella. I kind of understand DTDs and style sheets.

I work for a manufacturerer creating parts lists, service manuals, and operator's manuals. I am most familiar with FrameMaker because most of my experience has been as a software technical writer (miss it). I thought I was going to oversee an implementation but it turns out they want me to create everything for this implementation.

Hereare a couple of things I've run into.

1. A co-worker is under the impression that we can style on-the-flykind of like inWord. He is a former Interleaf user. I say thatweneed a DTD first even if it is a simple DTD because those styles apply to the DTD elements regardless of our output. Ouroutputis PDF. I know I'm 99% right but I just want to confirm.
3. My boss doesn't understand why it is so difficult to create all of these pieces. I have small snippets of code from a DTD and style sheetto show him. I've explained about thedocument analysis,defining information, identifying reusable content,and so on. What am I missing? Can I do all of that aftergoing through PTC University? Most of our DTDsshould be pretty simple. The most difficult thing I anticipate is auto-creating thetables of content and indices. Also we only have Intralink or Windows for storage and reuse.

4. If I can get through this, I'll have a feather in my cap.

   Ginger Shew-Stuckey

[bibach]

Hi, Ginger...

You've come to the right place. 🙂

Your co-worker's impression isn't completely wrong, in that you tag
the information as you go, but tagging is (mostly) about indicating
what the information *is*, rather than how it should *look*.
Separating these two things, which have traditionally been mingled
together in documentation and publishing, is what allows your
information to be more robust across changes in styles and even in
presentation mediums, such as going from print to various electronic
forms, for instance. Once authors get the hang of the new approach,
they'll almost certainly find that they are more productive, as well,
since they won't be spending time playing with the style of their
document, which tends to be a pretty time-consuming process. The
style of your documents will likely be more consistent, as well.

As far as explaining the intricacies to your boss, perhaps a
manufacturing analogy would help. I'm a computer geek, and have been
since a very young age, so I'd be of limited use on a factory floor.
That said, I follow directions pretty well, so as long as you can tell
me exactly what to do, I could probably run the machines. However,
I'd have no common sense when it comes to recognizing that something
isn't quite right, or knowing what to do when exceptional
circumstances arise. If your instructions don't tell me all of these
things, down to some pretty excruciating detail, things could go
pretty badly.

It's the same with trying to get the computer to understand the nature
of your documents and the styles that should be applied to them. You
need to make sure you're giving the computer a very accurate and
precise description of all of the rules of your documents' structure
and style. Fortunately, the Arbortext tools make the process easier
by helping you leverage common patterns that arise in many
documentation efforts. It's still up to you to decide which patterns
to use, but once you do, they'll help you make quick progress.

Hope this "sermon" helps. 🙂 Feel free to follow up with additional questions.

-Brandon 🙂

Brandon Ibach
Developer, Single-Sourcing Solutions, Inc.

[naglists]

Hi Ginger,

[ebenton]

Don't forget Suzanne Napoleon's favorite sig: WYSIWYG is last century technology.

[lfraley]

Love it! I always said it was WYISOP: What you see is one possibility.

[ClayHelberg]

Hi Ginger-



Welcome to Adepters! I agree 100% with what Paul and Brandon have said,
and wanted to amplify just a bit.



Re: why we go to the trouble of all this: the big payback on all this
effort is the ability to automate a lot of what used to be done
manually. Automatic formatting gives big dividends, especially in the
case where you have multiple output formats (like HTML and PDF) that
contain essentially the same content. But even with a single output
format, you don't need a very big shop before the effort of one
stylesheet developer (who would most likely be you) pays for itself in
time savings for the rest of the authors. Suppose your authors are
currently spending about 1/8 of their time adjusting formats, page
breaks, fonts, headings, graphics, etc. etc. If you set up a system that
automates all that, so authors can concentrate on content, then you only
need to support 8 authors to completely pay for your full-time position.



A system like that also gives other benefits, such as:



1) Consistency of format across documents; formatting is handled by
a centralized stylesheet, so you don't have to worry about Joe who likes
to make titles 24pt and Sally who makes them 25pt

2) Consistency of content, depending on your DTD; for example, if
every "example" topic is supposed to have a "description", you can set
up your DTD/schema so it's more or less impossible to write an <example>
topic without a corresponding <description>.

3) Provides a simplified path for translation/localization, if
that's an issue for your shop

4) Adding a new output format is as easy (and as hard) as
developing a new stylesheet. If you've been producing PDF, and you get a
requirement to produce web pages too, you can develop an HTML stylesheet
and then voila! All your content can now be published to HTML.



Re: what it takes to be an XML application developer, Paul's right, you
have to be able to think like a programmer, and you're better off if
you've done some actual programming. OTOH, I'd say nearly everyone on
this list, and generally most people who maintain these kind of
applications, are self-taught, having learned the whole process as they
went. So don't despair at your lack of experience-most of us "experts"
were once exactly where you are now.



Re: styling on-the-fly: If by that you mean that it's fairly easy for
the stylesheet developer to create the look and feel that the
organization requires, then that's more or less true (once you master
Styler's somewhat idiosyncratic UI). But if you mean the Frame-like
ability for each individual author to infinitely tweak their documents
to their own whim and desire, you won't have that-and that's a Good
Thing(tm). As I pointed out above, one of the primary benefits of a
centralized XML-based authoring and publishing system is that it frees
up the authors from having to noodle around with the formatting
trivialities.



Of course, many authors who haven't done structured authoring before
*like* the complete control they have with something like Word or
FrameMaker. They *like* to be able to tweak the line spacing when they
have a little extra whitespace at the end of a page, or to be able to
stick tabs in there to make things line up "just so". So, you will have
some work to do in getting them to make the paradigm shift from WYSIWYG
authoring to structured authoring, where the most important thing is
getting the markup correct. The authors will have to get out of the
habit of worrying about formatting minutiae and trust the stylesheet to
do the right thing once the markup is correct. You may have to do a bit
of hand-holding to get some of the more intransigent authors over that
hump, but my experience is that eventually even the die-hard tweakers
will eventually see the light and embrace structured authoring.



And finally, as you ramp up with your Arbortext system and start running
into issues, I'd encourage you to take full advantage of this list. It's
an incredible resource, with lots of smart and experienced people.
Usually you'll usually get answers here within minutes or hours of
posting a question. And you'll be surprised at how quickly you'll be
answering other people's questions. 🙂



Good luck!



--Clay

[naglists]

WYSIWYN - What you see is what you need. I forget whose that was. Some
Arbortexter's, I think.

On Wed, Oct 21, 2009 at 7:18 AM, Liz Fraley
<liz.fraley@single-sourcing.com>wrote:

> Love it! I always said it was WYISOP: What you see is one possibility.
>
>
>

[ptc-918094]

Hi Ginger,

I would like to add to one of Clay's comments:

<snip> ... The authors will have to get out of the habit of worrying
about formatting minutiae and trust the stylesheet to do the right thing
once the markup is correct. You may have to do a bit of hand-holding to
get some of the more intransigent authors over that hump, but my
experience is that eventually even the die-hard tweakers will eventually
see the light and embrace structured authoring.

In almost 20 years of doing SGML/FOSI with various writers, some of the
die-hard tweakers still tweak and they will find very inventive ways to
maintain their "format fiddling" abilities.

Like the others on this forum, there have been days when I wondered why we
made the move to this environment, but 99.9% of the time I'm glad we did.

Sue

[ptc-1908075]

Welcome Ginger!

Re: "WYSIWYG is last-century te technology," WYSIWYG is based on the typewriter -- when was the last time anyone used a typewriter?!? The problem with the WYSIWYG approach is that it means functionality must be hidden, which tends to make the software difficult to use. And this approach does not scale up very well. The more new automated features that are added, the more difficult the software becomes.

Also, WYSIWYG software must rely on artificial intelligence, which can never be as good as the real intelligence that comes with structured markup. That's why the results of switching to SGML/XML can be dramatic. I know of one organization that produced one publication every two weeks using their WYSIWYG software. With their Arbortext Editorapplication, they produced more than one publication every day!

How is this possible? Newer, better technology than WYSIWYG.

Re: formatting, some folks estimate their authors spent as much as 50% of their time on formatting with previous WYSIWYG products -- and all that effort resulted in documents that were not consistently formatted! (When I started my first FOSI development project, I soon realized that no two sample documents were alike.) With a batch formatting process, you can build the formatting specs and corporate identify and style guidelines into the stylesheet and get consistently formatted output every time -- in less time than before!

To help authors make the break from WYSIWYG, I recommend using a screen FOSI whose purpose is to facilitate authoring not mimic print/PDF output. For example, the attached screen-font.bmp shows the Edit window formatted with a screen FOSI that attempts to replicate formatted output, including the generated asterisks. Compare it to better-screen.bmp, which is formatted with a screen FOSI that uses an easy-to-read font and size so authors don't need to zoom in and out. Color, rather than size and white space, distinguishes chapter and section titles, which means more content fits on the screen and authors don't need to do so much scrolling. Everything is flush left, which is also helpful for authors.

A screen FOSI can help authors in other ways. For example, the attached guidelines.bmp graphic shows a message in the Edit window that does not need to be deleted and will never appear in print -- unless you want it to. For example, the attached 30days-editor.png shows messages in the Edit window, while 30days-print.bmp shows the print/PDF output of the same source file with different messages.

Another example: The attached profile1.bmp shows the Edit window formatted for a subject matter expert to author/edit the Part Description. Everything else on the screen cannot be changed. With a different FOSI, the same content could be displayed in an entirely different way, with all content available for editing.

In addition, you can rather easily develop a print stylesheet that supports a double-spaced, single-column, draft printout in a monospaced font so the content can be reviewed independently of the formatting.

You may also want to check out my Top 10 Reasons Tags Are Better at

[gstuckey]

Thank you all very much. You've given me a lot to think about. I have a couple of DocBook books that I am studying as I take the PTC University courses to learn ArborText. I just need to digest it all.

This is where I want to take my career so I'm sure I'll be asking lots of questions. But for now, I'm going to knit!

Ginger Stuckey
Technical Publications Specialist
Heil Environmental

PS. Yes, I do know how to drive and operate a garbage truck.

[ptc-953343]

Why DocBook? Have you considered DITA?

..dan

[ebenton]

Is that "knit" as in what your bones do after they're broken, or "knit" as in making things out of yarn? 😉

[ebenton]

I have no experience with PTC University, but perhaps DocBook is what they use for their classes.