How can I manage screen shots and other graphics for maintenance?
Our ~1500-page documentation set contains numerous screen shots and related graphics (schematics, flow diagrams, etc). Sometimes the user interface changes and we have to update all the affected graphics. The affected graphics are not necesarily all in one book; they can be spread across several. In short, they could be anywhere, so we rely on writers' knowledge of the doc set and sometimes just paging through the whole thing looking for graphics that are no longer correct. The first is fragile and the second is tedious (and also can be fragile).
Within the XML doc source itself I can (and do) embed internal tags that I can later search for. Think of that as meta-data for the docs. I'm looking for a way to associate meta-data with images, so I can find all the images that show such-and-such feature or such-and-such widget or whatever. I could set up an external index file or database, but that means the meta-data is far from the images and I worry about it staying up to data (will every writer always remember to update the database when he creates or edits an image and its meta-data changes?). Is there anything clever I can do to get the meta-data closer to the data?
Image formats are PNG for screen shots, GIF for line art. Is there any tool that would let us embed, and query, meta-data right into files in those formats?
Our existing relevant tools are: Perforce for source control, DocBook XML for the doc source, Ant for build targets. On the graphics side, we use PaintShop Pro and/or SnagIt for taking/editing screen shots, and mostly Visual Thought for line-art (though we have access to InkScape and can learn it if that would help). Our desktops are Windows (XP now, 7 later this year).
Edit: The screen shots also have text implications -- we usually don't just have a screen shot, but rather a screen shot and text that talks about the options or what you can do with that tool. The screen shots are integral to the documentation, and if a screen shot has to be updated we also have to look at the places where that image is used. Finding those points in the text is easy (I can just grep the source for the file name of each image when I update it), but finding the screen shots that have to change in the first place (because the UI changed) is much harder. This question is about managing that process so we can keep all the documentation up to date.
1 answer
For the book I am currently writing, which is not written in docbook directly but is written in a markup that will be translated to DocBook for publishing, I use an XML file to capture metadata for each illustration.
<?xml version="1.0" encoding="UTF-8"?>
<image>
<source>assemble.svg</source>
<fo>
<href>assemble.svg</href>
<contentwidth>4.25in</contentwidth>
<align>center</align>
</fo>
<epub>
<href>assemble.png</href>
</epub>
<alt>
<p>A diagram showing multiple pieces being combined in different ways to produce different outputs.</p>
</alt>
</image>
Because the book will be published to both paper and ebook, we need different file formats for each graphic. Here the source graphic is assemble.svg and the same file is used for print (fo means xsl-fo). But for epub, which does not support SVG, we use assemble.png. The XML also provide an alt for the graphic and lets you include sizing information as well.
When I include a graphic in the book, the include instruction actually points to the XML file rather than the graphic file directly. The processing code then reads the XML file and generates conditional DocBook markup for use with each version of the book build.
This approach gets around any difficulties with including metadata in the graphic files themselves and allows you a level of abstraction that will let you use different file formats for different media.
Something similar should be workable for your builds. It will simply require either some preprocessing of your source files or some additional rules for processing graphics.
The downside of pointing to the XML file rather than the graphic is that the graphic will not show in a graphical XML editor. But there is a way round this. Rather than pointing to the XML file in the source, point to a graphic file as normal, but rewrite the processing code for the include instruction to strip off the graphic file extension and read an XML file of the same name in the same directory.
0 comment threads
0 comment threads