Top 10 Word issues

There are zillions of "issues" with Word - this list is just a starting point for a discussion on things that a technical writer should probably understand.

1. Layout, sections, headers, footers.
2. Styles.
3. Numbering.
4. Search and Replace, and Goto.
   
5. Document properties, and bookmarks.
6. Templates, and security, access, and macros/VBA.
   
7. Fields, TOCs, Indexes, Captions.
8. Images.
9. Mail merge.
   
10. Office 2007 ribbon, and other new features.
    

Top 10 Flare issues

This is a fairly arbitrary list - each item needs a discussion. It is neither a top 10 Best or Worst - just stuff that has to be thought through. I've put some things together just to limit it to 10.

1. Interface and Editing.
   - layout, XML editor, those bars, other editors, multi-tabs open.
   - HTML, hyperlinks, cross-references.
   
2. Word
   - import and export
   - round trip.
   
3. CSS, Skins, and Dynamic HTML.
   - the CSS editor, Flare custom styles.
   - print, screen, Word mediums.
   - togglers, and drop-downs.
   
4. Templates and project set-up.
   - project templates, topic templates.
   - master pages
   - sharing information between projects.
   
5. Targets, TOCs, Destinations, Compiling, and Reports.
   - include merged projects.
   - log files.
   
6. Indexing, Browse Sequences, Glossaries, Searching.
   - the good, the bad, and the ugly.
   
7. CSH - Context Sensitive Help.
   - who should do this - developers or writers, or both.
   - header files, alias files
   - use a URL call or a javascript call.
   
8. Snippets, Variables, Conditions.
   - single source.
   - distinguish content by choosing tp set conditions, or place in snippets.
   
9. Images, and Sound
   - resolution
   - sharing between print and screen
   - screen captures
   - recording
   - discuss other Madcap tools.
   
10. Source control.
    - multi-user support
    - manual or bind a project.
    - issues about networks or local drives.
    

Is Flare Easy?

Clearly, we're all different ...

One of the reasons I (with my team) chose Flare is because it was EASY to use. From the first day of our trial we were up and running and generating output, and we would not go back to the other tool. The beginner's tutorial was useful, and I've learnt stuff from the helpfile.

Now, we've had issues, and we had to learn stuff, I won't deny that, but I think it's in pretty good shape. Using the XML editor was different, but if you really don't like it, use one of your own choosing - in a team environment that is a plus. I don't like the CSS editor, but I can set up a .css file elsewhere and bring it into a project seamlessly. And it generates all the output types we want.

I probably wouldn't buy a book nowadays (apart from the fact that there is no more room on my shelves). I'd rather see the Knowledge Base expanded. I don't think there is enough room in a book to cover best practices. Books tend to see things from one point of view - a knowledge base or a wiki (or a forum) can have far more examples and scenarios. I'd support the "writer's centre" concept mentioned earlier - a place to download templates, and skins, and scripts, ...

Just my two cents.

Freelance writing

This article has some interesting comments about freelance writing, and websites that pay for content.

http://apnews.excite.com/article/20080324/D8VJU81G0.html

Women's studies

The Women's Studies course is disappearing in the UK.

Swimsuits

The latest design of fast swimsuits is in the news at the moment. There are questions about its legality because of all the world records that have been broken recently.

Is this a problem with correlation and cause and affect? I thought that in the lead up to the Olympics, particularly at the time trials, we always see records broken as swimmers are trying real hard to do what they've been training to do for years?

Earth hour

I have to agree with Tim Blair's comment about the earth hour gestures. How can you possibly claim to support (the ridiculous) earth hour when all you do is change the time of the lighted activity. You still use the same amount of electricity. Will the candle light vigil afterwards actually mean more carbon is put into the air?

Maternity Leave

There have been a number of articles in the papers recently about whether Australia should set up paid maternity leave. There are a number of issues, some of which have been addressed, but some are still open for discussion.

1. Who pays?

• The proposals put forward are that the Government pays, not the employer. It seems a tad obvious, but if the small businesses had to pay, then work for women in their child-bearing years could become much more difficult to get.
• Monetary-wise we can accept that the gov is the right group to pay, but is there also some cost in time? Training someone to have them disappear soon after may also be unofficially frowned upon. Having them come back part time can also have a hidden cost.
  
• There are organisations who feel that if a person is worth having, then it is worth helping them to manage their time during the early years of the the baby.

2. Why maternity leave from work? What about "non-working" mothers?

• Maternity leave seems to imply that you get money if you were working. What about those women who get pregnant between jobs - why should they be left out?
  
• The options put forward claim that we should be encouraging women to use their skills and training - why imply that women who have "momentarily" left the work force are somehow not worth as much.

3. Isn't this the baby bonus only less?

4. How is the payment calculated?

• If you have a high paying job should you automatically become a highly-paid mother?

I think there are too many problems and prejudices with the set-up for maternity leave. If we want to encourage "baby-having" then why not work out a better baby bonus, or a better set of tax cuts, or something.

Update: Some references:

• Parenting article in Age 26 March.
• Pru Goward's comments - the Age

Keeping secrets from the bad guys

The young prince had to be sent home from the front line when Australia's New Idea ran a story about his where-abouts. The British press had agreed to a media blackout in the hopes that his unit would not become a higher target while he was in service over there.

But you have to wonder, if the Aussie press could get a hold of the story, do you think maybe the bad guys might have been able to find out as well? Just how top secret was it?

Or did another royal release the story just to get him home?

Word commands

You can use an Auto macro (old fashioned Word if you can't use events), or hijack an existing Word command in 2 ways:

• Create a subroutine in any module with the right name (AutoSave, AutoNew, etc, or FileSave, ...)
• Create a module with the name you want with a module called Main that has the code.

Auto routines are:

• AutoExec
• AutoNew
• AutoOpen
• AutoClose
• AutoExit
  

Set up basic word styles

Set up a font, and click default.
Set up a language, and set up default
Page size defaults.

Make this a macro that can be run from the toolbox.

Office 12 help

The people at FAR have documented how to add your own help topics to the latest Office help files. See:

http://www.helpware.net/mshelp2/CollectionWizard/Office12Help.htm

How do you create side bars in Word from Flare

Can it be done with a master page?

snippets and single source

So should you create one huge document and put in condition tags,
or
create lots of little snippets and build it all into a topic.

If you are trying to think DITA, the latter is the way to think, but is this practical in Flare?

Getting to work in any weather

Links to green house issues and "monash professors"

http://www.theage.com.au/news/environment/benvironmentb-scientist-warns-that-the-car-is-doomed/2008/03/02/1204402272871.html

http://ker-plunk.blogspot.com/2008/03/moronic-monash-uni-professor-proves-hes.html

These articles need some discussion and

"user" scenarios

There are a number of scenarios for Flare/Word usage:

*** table deleted - did not transfer.

Headers, footers, master pages, templates

You can generate running headers and footers for your Word output, but bringing them back in is a nightmare.

Styles and the print medium

For output to Word, you have to get your print/online medium in the CSS file right. Think about:

• Font styles and sizes for body and headings
• table styles
• basing the heading levels on the toc levels.
• Numbering in Word but not in online.
• Hiding text in Word that displays in online.
• 
  

Import by copy

What gotchas are there when you copy and paste from Word.

Spacing and formatting bullets is a major issue.

Flare At Work

The Flare At Work help file is a set of more detailed help topics on how to really put some of the Flare features to work. If it had to be categorised into modern book titles, it would be more of a "Flare, the missing chapters" rather than a comprehensive "For dummies" or a "Cookbook" style. Some of the details need to explain how we do stuff at Computershare.

OK, so it's a bit of a play on words - on the one hand, we want to make Flare really work, and on the other, we describe the standards at work!

Using the interface is covered in the tutorials - we need to cover stuff like:

• Setting up our project templates.
• What CSS files we use.
• Word Import
• Word Export
• Naming conventions
• Snippets, Variables and Conditions.
• Home Made DITA
• Home Made Browse Sequences
• Master pages
  

Of course, some of this stuff has been included on our wiki. The help file will let us generate Word documents and articles, and so on.

Exporting to Word from Flare

Things to think about:

• Styles
• Print and Online mediums Vs a custom "msword" medium
• Master pages, multiple master pages even.
  
• TOCs
• Heading levels and TOC levels
• Conditional Text, snippets and variables.
• Images - size, shape, resolution
• Save as .DOC or .XML
  

One of the big issues in exporting to Word is making the styles work in a "single-source" manner. That is, you should be able to have the content in a set of topics that you can pick and choose no matter what the output format is. With online and printed output, you often want different fonts and styles. Cross references and hyperlinks are often different - in one you might even want page numbers.

Resources Folder in Flare

How is the Resources folder in Flare managed?
Are images that are stored there always added to the output, or only if they are linked.
Compare to an images folder in Content - all images without a condition tag are included in all online builds.

Importing Word to Flare

Ways to import, and the issues that arise:

• You can import a document and make it a new project.
• You can add one or more Word files to an existing project.
• What happens to graphics.
• What happens when you re-import.
• What if you add a whole new section to the Word document.
• Or delete one?
  
• Should I preserve or ignore Word styles.
• Should I generate a new CSS or use one I cooked earlier.
• How should I split the Word document.
• Standards Schmandards - what do you mean "naming conventions"
• What's with the folders that get generated.
• Is that master page of any use at all?
• How is the TOC generated?
• You can maintain a link to the imported documents, or cut the connection.
• Import as copy/paste.
  

Things I'd like to see:

• Split a document into sub-folders.
• Have some say in the file names - get rid of spaces for starters.
• Have some say in the graphic file names.
• Set my default Options - I want to start all options cleared - is this a Project Template thing?
  
• Map paragraph styles - need to be able to map independent classes.
• Importing headers/footers/master pages just don't work - not sure yet how to fix it.
  

Articles for Southern Communicator

I have been asked to write an article for the ASTC magazine, Southern Communicator on something to do with Flare. I think there is definitely a topic on Word imports and exports, and even go as far as round trips.

Other ideas include working and learning new tools in a team.

Do we really need to know CSS?

And what about javascript?

How about a technical article on Home Made Browse Sequences.

A list of possible topics

Technical stuff on tools that I use

• Word - this needs to expand
  
• Excel and other office stuff
• Flare
• Other help tools
• Indexing
• Single sourcing
• DITA and new "technologies"

Expand on Word and Office

• Moving to Office 2007
• Mail Merges, envelopes
• Creating Labels
  
• Settings
• Revisions / Track changes
  
• Styles
• Headers and Footers
• Landscape Vs Portrait
• Tables
• Text Boxes and Frames
• Autotext, Auto Text
  
• Setting tabs and other alignment work
• Language and spell checking
• Borders
• Bullets and Numbered Lists
• Paragraph numbers
• Cross references and hyperlinks
• Short-cut keys
• AutoSummarise and Research
• Task Panes
• Choosing a template
• 
  

Next steps

I have started writing some stuff here, and not finished it here - but this is a great starting point. Some stuff needs to go on to be in a blog at work.

This blog will morph into a scratch pad, but I'd like to create a more technical one that I post to once a week.

It's still a great place for writing exercises. In the recent email from The Journal, the exercises were in categories of:

• Journal
• Memoir
• Prose
• Free Writing
  

And another thing, there are way too many blogs with the name like "on writing ..." I can't publish this one.

Do technical writers RTFM?

What writers do

One of the things that most tech writers say in a job interview is that they are very good at learning new systems. That's part of what makes them a tech writer - they try out the system, understand it, then write about it for all the other people who need to know it, using proper grammar, of course.

So what do you expect when a new help authoring tool comes on to the market? Does an authoring tool need a help file? Can the tech writers who want to use it just use their super-hero style abilities to learn the new system quickly by trial and error?

Ah, yes, it does, and no, they can't.

What writers use

I have recently had the pleasure of moving from RoboHelp to Flare (where recent is about 18 months). There were a number of technical reasons and a number of support issues for the move - all have been discussed at length by others elsewhere. I am one writer in a group of 5, all with RoboHelp experience, and all with extensive Word experience. There is a smattering of Framemaker, PDF, HDK in amongst our collective resumes as well.

How do they learn

So what did we, the team and I, do to get up to speed on this new authoring tool?