Subscribe to RSS
Posts Tagged ‘DITA topic’
Getting Started with DITA
I have gotten two similar questions about getting started with DITA in the time span of about two weeks, so I thought I’d borrow from some of my answers as a write-up for a blog post. One person wants to ditch her Adobe toolset in frustration and try out some DITA workflows with all free tools. The other is a lone writer in a small shop and wants to find out more about DITA and see if it might work well in her Agile development environment. While I’m a huge DITA advocate and see many ways that DITA can help with many doc goals, I don’t think that DITA has all the answers necessarily. Topic-based authoring with just concept, task, and reference types is a different mind set for both writing and publishing. But, you could certainly put together a toolkit of freebies with DITA to try it on for size. So here are some starting points.
Get very familiar with topic-oriented writing
Without some up-front information architecture and design where you really analyze your documentation needs, and figure out what task, concept, and reference means for your body of work, DITA won’t help you. Transforming legacy information into topics may or may not be a worthwhile effort so some up front analysis will help you.
Bare minimum tool set to “do” DITA
You’ll need the DITA Open Toolkit, available at http://sourceforge.net/project/showfiles.php?group_id=132728. Here are direct links for the 1.3 package that you just download and unpackage on your hard drive. Windows zip Linux tarball
These full packages of the DITA Open Toolkit contain all the sub-tools that you need for full evaluation from authoring to building output. Most of these tools require the Java Platform, so, Java is a prerequisite to using the DITA Open Toolkit. Download and install the Java Platform Standard Edition (SE) 5.0, available at http://java.sun.com/j2se/index.jsp.
Ant 1.6.5 runs automatic builds on your DITA maps, and the DITA Open Toolkit gives you ant scripts for builds already.
Xalan-J 2.6 is an XSLT processor which is required to run the transforms.
FOP 0.20.5 is needed for PDF output. (Note: For compiled HTML help (CHM) you’ll need the HTML Help Workshop, which isn’t included in the Open toolkit, but most help authors will already have this installed.)
ICU4J 3.3.4 is included for improved NLS-enabled index sorting.
Apache Catalog Resolver 1.1 is a standard XML catalog mechanism.
Plus, the newest full package (1.3) contains a startcmd batch file in the root folder that you can use to set up your environment each time you run the DITA Open Toolkit. Considering what headaches I had just with environment variables in Windows, I am greatly appreciative of this little batch file.
If you want to first just look at topics and create some output before authoring anything of your own, look at the EvaluateOT.html file in the root directory of your DITA Open Toolkit install. Double-click the startcmd.bat file, then type ant samples.web -f build_demo.xml at the command line and you will have your first set of DITA output in a newly-created \out folder in your DITA Open Toolkit installation folder.
When you want to create your own topics and maps, you’ll need an XML editor. While you can certainly edit DITA XML in Notepad, you’re going to want a validating XML editor for serious authoring and evaluation. See my suggestions next.
DITA XML Editors
Previously I posted my notes from Don Day’s talk at the Central Texas DITA User’s Group about evaluating DITA editors: http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-editor-eval. Now, the next step for me is to start naming names. Let me be clear, though, since I’ve been on maternity leave for the last six months or so, I haven’t been seriously evaluating XML editors for BMC. Others are doing that and I’ll be happy to use whatever they recommend for our environment. But, for my friends who have been asking me about DITA, let’s break this evaluation into free and not-so-free. Note: nearly all enterprise-level XML editors have 30-day trials, but it’s tough to get enough done in a 30-day evaluation of DITA and the XML editor if you’re just starting out with topics and DITA.
Awareness of DITA is not always an easy achievement, apparently, and when you’re new to DITA, it’s tough to evaluate “DITA aware.” So I guess you just need to trust others when they say an editor is a DITA aware editor.
Free XML editors
XML Copy Editor – this open source project has an XML editor that claims to support DITA. https://sourceforge.net/projects/xml-copy-editor/
DITA Storm – this is a free web-based DITA editor. You can either install it yourself if you have a web server, or try out the ditausers.org online web-based editor for free (use the coupon code BETA) during the evaluation period.
Enterprise-level XML editors (with 30-day free trials)
I believe that you should convince your manager you need this level of editor if you’re serious about writing DITA topics for end-user doc.
Bob Doyle has done an excellent job of evaluating XML editors in this article, X Marks the Spot: Let’s Take Today’s XML Content-Creation Tools for a Spin, complete with tables of prices, platforms, support info, all the specs you’d need to evaluate a tool for your environment. The ones I have installed and tried are: Adobe FrameMaker ($799), Arbortext Editor ($695), XMetaL Author DITA Edition ($895), and Syntext Serna ($195). You would have to determine what’s right for your particular environment and preferences.
What to do to start writing DITA topics
Open your XML editor and start with either a concept, task, or reference topic type. Or even start with a topic to begin with. Write some content, and validate it as you go. Once you get a handful of topics, make a DITA map either using the code in an XML editor or using a DITA Map editor like the Task Modeler available as an Eclipse plug-in.
What to do to get output from your DITA topics
You can modify the ant scripts provided with the DITA Open Toolkit for your own builds. I was able to do a few ant scripts just based on the template files and examples the toolkit provides. I used the “ant/ sample_htmlhelp.xml” template to make this build file for my map file named processfile.ditamap on Windows. Edited: to link to the sample build file code instead of posting it here because apparently our DIV layout doesn’t like wide-width PRE areas in the middle column. 
Nice-to-have tools for anything beyond just evaluation
You’ll want to automate building output with Ant. The example build file above gives you a start, and there are plenty of templates provided in the Toolkit.
Once you think about enterprise publishing, reusing topics across groups, and so on, you’ll want to use a Content Management System. I think CMS tools for DITA is an entirely different topic that deserves more research so I won’t say more than that yet. To get started on larger doc sets without a CMS, use a logical folder structure and defined file naming conventions, then use the OS search tools to look for metadata within topics.
A DITA map editor that either integrates with the CMS or the free Task Modeler from IBM has a really good visual method for editing DITA maps.
More reading
I like the Introduction to DITA: A User Guide to the Darwin Information Typing Architecture book available here.
The DITA Open Toolkit User Guide and Reference is very useful as well, and free.
Bob Doyle, an active member of the Boston DITA User’s Group, also has a helpful article in the E Content Magazine column, I Column Like I CM: Getting Started with DITA.
Use Don Day’s evaluation heuristic for editors if you want to do a full-blown evaluation for your preferences in an authoring tool.
Everyone must read Scott Abel’s article, 10 DITA Lessons Learned From the Trenches on the Content Wrangler when evaluating DITA for their doc needs.
Anyway, once you get very far with the DITA Open Toolkit you might fall back in love with the Adobe toolkit. I’d love to hear just how far you get and whether you fall in love.
Turning information into DITA topics
I’ve been looking at content at BMC and determining whether it belongs in a concept, reference, or task topic using DITA’s definition of a topic. I had one particular item that seemed like it could be arranged in several different ways with advantages and disadvantages for each method. I had a great conversation with a fellow writer and a technical editor in the car on the way back from our corporate offices in Houston, and I thought I’d capture that discussion in a blog entry. So here goes.
Background information for this task
Overall, the user wants to configure their shiny new BMC Performance Manager for Databases product. It’s a pretty flexible configuration process to accommodate the needs of different environments but also to balance out ease of installation and configuration. So, you can either have the product automatically configure everything (you have to have certain user permissions on certain objects to do so) or you can manually configure by editing some included scripts that will give the correct permissions to each individual object (also requiring certain permissions but gives you the exact knowledge of what’s happening to your database).
So, as you might have guessed, the manual configuration goal turns out to be the toughest to turn into topics. I decided to look at the tasks related to manual configuration and then write the supporting topics.
What’s the task here?
But is the task itself “manually configuring” or is it “editing scripts?” I finally decided the task itself is editing the scripts, much to my chagrin because it doesn’t sound like a goal-oriented task. In addition, the background information for knowing why you’d do auto vs. manual should be explained in a concept topic, I believe.
But here’s where the decisions got a little tougher. The supporting reference information is a table of the objects and the required permissions on each. Obviously exactly the sort of information the DBA needs to know to get the job done. However, the complication occurs when I see this big table listing the script names — is that a second reference topic supporting the task of editing scripts? It’s only two columns but it’s a matrix of three supported databases with at least three script names for each. It’s essential information, required in order to complete the task of editing a script for manual configuration.
Do you put reference info in with the task if it’s critical for completing the task?
So do I keep that reference information with the task itself to avoid separating it into a standalone topic? Or assume the reader might come to that topic from many different directions so it should be by itself but in a related links link from the task.
Final decision - make it a topic
In the end, I decided that for ease of reuse and to offer multiple entry points to the information, I would make the script table standalone as a separate topic. It seems like the benefits are that the user can find that topic more easily and also that reference info can be related to other tasks as well. Other deliverables may also want to include that reference information so designing for re-use seems like a benefit here as well.
I’m still a little uneasy about my final decision to make four topics out of what is essentially one end-user goal — to manually configure their product. Does anyone who does topic authoring often have any suggestions?
Parting thoughts on the complexity of software documentation
This type of configuration complexity is why many examples in topic authoring presentations and articles ring hollow to me. Examples of the portability of telephone pole repair manuals and the task-orientation of cell phone manuals are not the types of concrete questions I ask myself every day when writing software doc. The classic example of “Hold the power button for 0.7 seconds” as a poor example of a step in a task immediately comes to mind. An equivalent software documentation example is much more complex than instructions for a task on a cell phone.
Software doc lives in the abstract. Instead of an easily known or recognizable metaphor, I’m faced with products that are increasingly flexible but that flexibility causes the user to be faced with many micro-decisions. I think it’s my responsibility to guide the user through their choices and offer the technical advice for them to make the best decision, no matter how they’ve approached the doc in the first place. (from a search engine? from the table of contents?) It isn’t easy but oddly enough I enjoy the hunt for the best content organization and chunking possible.
