Monthly Archives: January 2016

Documenting XML in DITA 1.3

We have XML configurations in some Wind River software, so we need to document those XML elements and attributes. When we document our DITA implementation for our writing team, we also mention XML elements and attributes. Here are my thoughts on our transition process, and on XML domains in DITA.

I am looking forward to replacing the DITA 4 Publisher’s XML domain with DITA 1.3’s XML Mention Domain. I think the only difference is that <xmlelem> becomes <xmlelement>. We will have to allow the old element “forever” since it is found in topics in our CMS, including tagged copies of our releases.

We are using Schematron to enforce rules in the oXygen editor, so we will likely use that to ask writers to change instances of <xmlelem> to <xmlelement> when they edit a topic containing the old element.

Also, we mention the names of our doctypes. We consider doctypes to be different from regular XML elements, so <xmlelement> is not suitable. We use (writing from home here – guessing the correct spelling) <doctype-name>.

Does anyone else mention the name of XML Doctypes in your documentation? Do you use <xmlelement>? What do you do instead?

 

 

Choosing a version control system for your Tech Pubs department

I assume here that you have already identified a need for a version control system. Choosing one may be your next step.

First choice: Use whatever version control system your developers use.

  • Your department may have to pay for a license on the server software, but you will have advice and assistance readily available.
  • Some of your writers will use it for different tech pubs projects and get proficient at a tool that is crucial to your company’s developers.
  • You may be able to piggyback your server license on theirs.
  • The IT department that set up their server for version control already knows how to do that. When you get your own server, they will already know how to set it up.

Second choice: Git

  • This is one of the most popular open source version control systems.
    Even if your company does not use it, you should be able to find help and advice in your development team. Check that this is true at your company before you make a decision.
  • Like most version control systems, there are GUI tools for Git, so you are not restricted to command line access to your data. On Windows, TortoiseGit is good, easy to use, and free.
  • Several companies provide commercial servers for Git, including Atlassian. Atlassian’s BitBucket server is inexpensive, but full-featured and easy to use and administer.
    There are open source servers for Git.

Other considerations:

  • Pay extra, if necessary, to keep your data in a separate storage area from the developer’s data. This storage area is usually called a repository, which is abbreviated repo.