File talk:DITA CONTENT STRATEGY EV-2009-12-11.doc
Eddie, December 11, 2009:
When I first reviewed this document, I was relatively new to the SAEAF project and didn't feel qualified to comment. At that point, I would have had more questions than input. After reviewing the document this morning, I have made numerous suggestions for revision. I have also added comments.
Note: When I uploaded my modified file, it appears to have replaced the one you originally posted here (?). I'm not sure about that.
Contents
About Date Locking
I replaced the document date with a locked Word field. The locking prevents the field from updating automatically.
Karen, when you revise and distribute versions of this document, you can unlock and update the field by following these steps:
- Select the field by dragging over it with your mouse.
- Press Ctrl + Shift + F11. This unlocks the field.
- Press F9. This updates the field.
- Press Ctrl + F11. This locks the field and prevents automatic updating.
Tip: You can tell if a field it locked by right-clicking and viewing the shortcut menu commands. If the Update Field command is dimmed out, then the field is locked.
Use of DITA Targets
The document seems to emphasize the use of DITA for print, or "books," and in DITA, print is just one output among many. The DITA architecture moves away from book paradigms. While you can use DITA to assemble a print-quality book, print is what many publishing tools call a target or scenario. The idea behind a target is that it is targeted for a specific audience or application.
Here are some examples of how we might use targets:
- Publishing for different audiences (e.g., executives, analysts, architects, developers)
- Publishing different sets of information (e.g., an online knowledge base, an entire book, or a chapter from a book)
- Publishing for specific applications: In MadCap Flare, I have a target for review comments. I add topics that need reviewing to a special TOC, then publish a PDF target with a cover page that automatically lists the included topics and enables them for commenting in the Adobe Reader. Another version does the same thing but publishes it to Word so that others can contribute to authoring. I set this up once and then run it automatically as I need it.
We can easily do these types of things with DITA, and I recommend that we capitalize on these capabilities as much as possible. Let's ensure that the SAEAF "book" is available as an online knowledge base as well as a printed document. I'm hearing a lot about PDF, but I'm concerned that HTML is considered secondary.
Use of Images
The document is not entirely clear on the use of images in DITA. This sections discusses points that we need to consider.
Embedded vs Referenced
The document refers to embedded images. Embedded images are literally placed in a document and travel with that document. This makes the document file size larger. We won't be using those in DITA.
On the web, images are stored in directories and referenced from pages using the HTML src attribute. DITA follows the same practice. We'll need to establish a central location for images and make sure that those images don't get moved. If we later decide that we need more than one image directory, we'll need to redirect topics with images to those new directories.
Note: Microsoft Word can actually reference images, too. You can point documents to image libraries using links. This isn't typically done, however, because Word documents are typically distributed in their native format. The recipients of the document will receive copies with broken links.
File Types
For our purposes, the .png, .gif, and .jpg file types should adequately support our work. Some of the formats discussed in the document are not typically used in web output (e.g., .emf).
In the days of desktop publishing, tech writing groups typically used high-resolution image formats for print (e.g., .bmp and .tif). With the increasing adoption of single-sourcing tools, groups have gradually adopted typical web formats for all media. I have used mainly .png, .gif, and .jpg for the last six years.
Rather than try to explain the difference between the three file types I mentioned, I refer you to these Wikipedia links:
Note: .jpg is good for high-resolution images such as photographs. It may also be good for some of our more complex diagrams.
Source Images vs Production Images
One comment in the document mentions placing Photoshop or CorelDraw files in our repository so that users can "grab them and insert them into Powerpoint presentations" or something to that effect. Remember that the native formats used by image editors (e.g., .psd for Photoshop) are not the formats we want to use in output--not even for PowerPoint.
Typically, if I need to capture an image for use in output, I simply capture it using a tool such as SnagIt. I then save the image as a .png, .gif, or .jpg and copy it to the image directory.
If I need to annotate an image, add callouts, or add effects such as torn edges or drop shadows, I use a tool such as SnagIt Editor or Photoshop. I save the file in the native editor format (e.g., .snag or .psd). Those tools enable me to create layers and add all kinds of effects. I then use the editing tool to Save As to one of the standard formats that I have mentioned ad nauseum in these comments. The benefit is that I still have the native source image, so if I need to modify the customizations, I can do that in the editor and then use Save As to replace the image used in the output.
Everyone may already knows this. I simply wasn't sure by reading the document. I want to clarify because this is the image production process that we should use with our DITA content.
