In DocBook, you’ll find structural tags like, ,, ,, and semantic tags like, ,, but nothing like, ,, , – nothing that has to do with layout or makeup.īecause of this, a decision has to be taken somewhere on how the DocBook tags are translated into presentational makeup. ![]() If you use undefined tags, or if you don’t follow the rules, your document isn’t DocBook anymore (and DocBook-supporting processing tools may break on it).ĭocBook tags always convey structure and semantics (meaning), never makeup. The DocBook DTD defines a limited number of tags, and it gives exact rules on how to use them: what attributes are possible for a tag A, whether element B can be nested within element C, and so on. The posting frequency can be very low at times, but rest assured that if you post there, your message will be read, and replied to. Talk about your ideas – or your search for ideas – on the firebird-docs list. Or maybe you can supply raw documentation material for a subject you know a lot about. Maybe you can write one or more chapters for a book. Maybe there are already people working on a larger production, which you can contribute to. You don’t necessarily have to write an entire book, guide or article. The most logical choice would be a topic you are familiar with, but you can also pick a subject you’d have to learn more about first (this is much more work of course, but a great learning experience if you’re willing to invest the time). Then ask yourself what’s missing, and what may be useful for Firebird users in general, or perhaps just for a specific group.Īlso ask yourself what you would like to write about. Translator’s notices in DocBookįirst make sure you know what’s already there – nobody’s waiting for three MS-SQL-to-Firebird conversion guides. ![]() A copyright notice at the start in DocBook Program listings, screens, literal layout, and examples ![]() A copyright notice at the start in AsciiDoc Firebird documentation AsciiDoc code style AsciiDoc and Asciidoctor - an introduction Updating the Firebird Documentation Index Publishing your document on the Firebird website Dos and don’ts if you have received commit rights Adding your document to the firebird-documentation repository Attaching the entire Public Documentation License I will try to expand each of them in posts that will follow in the coming days. Each of the step listed above needs further explanation. The above steps are of course in their over simplified form. Start moving the content from the MS Word file to individual topic dita files.Decide the file name for each of the topics that need to be created.Look at the contents of each topic in the MS Word file and decide if its needs to be split up into smaller topics.Go over each item in the MS Word TOC and try to classify the topic to its most appropriate DITA topic type equivalent.Create an excel file to help with planning the MS Word TOC to Dita Map conversion.Review the table of contents of the MS Word user manual.The top level steps that I went through when converting the MS Word User manual to DITA was something like this: To get a crash course in DITA this nifty tutorial written by the kind folks at XMLMind is a must read. The DITA content types that I used so far are: The DITA WayĪlthough I do not want to talk much about DITA itself in this post, writing technical content in DITA meant that, as an author I had to start thinking differently than when I was writing the user manual in MS Word. I find the editor really instructive and I feel that I am learning how to create valid DITA topics as the editor constantly checks and corrects me. ![]() One of the most valuable features that I found to be useful was that the XML editor checks if the content that I type is valid DITA as and when I try to add a new element into a topic. It has excellent support for authoring content in the DITA format and makes the job of the content author super easy. The tool was chosen for the DITA implementation at our company was the oXygenXML Editor. In this article I will write about how I converted a MS Word user manual to DITA. The company wide decision was to move to DITA. One of my first assignments in my new job was to convert the existing user manuals that were created using MS Word to a more modern documentation framework.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |