by Søren Weimann | Apr 22, 2020 | Blog
“Looks cool, but couldn’t we just stick to what we have?”“Being able to grab a piece of content like that would be nice, but I don’t have the time to learn this new tool.”“Yes, I’d like to be able to publish a white paper using parts of your updated documentation, but all these tags and attributes? I don’t know…” We have all heard these complaints. Since DITA XML became an open standard and DITA 1.0 was released in 2005, people have been trying to spread the use of modular and structured content beyond the traditional documentation department. Some have been successful, but many have been hitting a brick wall when they present XML templates and XML tools to Marketing and Development departments. Time and time again, I myself have presented the opportunity of sharing content, reusing topics, conrefing legal notes and filtering output for different target audiences. They all see the benefits, but more often than not, they take one step back when they see the tools, the interfaces and appearance of overwhelming complexity. Some rule it out entirely and some have a hard time finding the available resource to prioritize the change process. Is this really the case all over the world of DITA XML? Well, before I just assume that my experience has any bearing on the world in general, I tried to find out if other people are experiencing the same thing. So I conducted a survey including 80 companies. Three types of implementations answered the survey. There are those that just aim for implementing DITA XML into one department. There are those that try to...
by Søren Weimann | Mar 2, 2020 | Blog
I’ve seen it first hand in several companies I have worked for: Field agents or other colleagues that work closely with individual customers come to me in the documentation department and ask me to make sure that their standard product documentation is always up to date. And then, they want to add a little bit of special information for each customer. “Oh, and by the way. In the field agent office, we have this standard guide that is only for us internal specialists. Can you make sure that is always up to date as well? Then I only have to go to the configuration database and fill in the form with the customer specific configuration information – by hand.” My reply to these guys has always been pretty simple, and the reaction has always been the same: I say, “Sure, we can do that, and that customer specific configuration information… you don’t need to fill it in by hand. The system can do that for you. All you need to do is write your part in DITA XML.” They reply, “That sounds great! But that DITA XML part… I don’t know. I know it’s really powerful, but I spent most of my day with customers, I don’t have the time to learn to write XML documentation.” A few times we get to the point of agreeing that they should learn to write DITA XML… when we’ve had some breathing room. But we never get around to actually making it happen. Customers always come first for these guys – and they should! Making the Field Agent NOT change So, what...
by Søren Weimann | Jan 5, 2019 | Blog
One of the main drivers in Open DITA is allowing writers with little or no XML skills to benefit from the most important reuse capabilities of the DITA standard. So let’s cherry pick from the rules of the Open DITA manifest and explain how they achieve reuse of your content. But before we get to that, let’s take a step back and consider WHY we want to reuse. Let’s be honest. Reusing content creates a certain amount of complexity. For that reason we had better make sure that this complexity is worth our while. Oh, and by the way – very often that level of complexity is already there, it’s just not always technical. Very often writers know that if they update a section describing a feature in one product, they must also update the documentation for variations of that product. If a legal note is rephrased, they need to find all the places it is used and copy/paste. The complexity is already there, and at the end of the day, the technical dependencies can actually help you manage these dependencies and ensure that none are missed. This leads us to one of the main benefits of reuse: consistency. Let’s keep it simple and stick with the most important benefits: Consistency across your documentation – When you reuse a topic, a piece of text, or an illustration, this minimizes ambiguous interpretations of the content. Honestly, if people are looking to enjoy variety in language, they will pick up a novel rather than my documentation.Less content to maintain and update – The second benefit is also the most popular among business cases for structured writing projects....
by Steffen Frederiksen | Sep 21, 2017 | Blog
Who cares about XML editors in the first place? Well, there are many different answers to that question. Ever since XML 1.0 became a W3C Recommendation on February 10, 1998, a lot of people realized that this new standard could be used for cross-platform publishing. The fact that an XML file could be processed by computers, and even transformed into other formats using XSLT stylesheets, was great news. Today, this XML characteristic of being machine-readable and processable is becoming even more important for new technologies. These include content automation, artificial intelligence, machine learning, deep learning, natural language processing, and chatbots or other software robots. Even though these new technologies are very smart and clever, they still need a lot of help to figure out what a text is about and what the relevant context might be. XML tagging with elements and attributes is providing this help. What is an XML Editor? Being entirely character-based, you can write perfectly valid and useful XML using Notepad. In fact, I have worked with people who preferred Notepad to any other tool, but fortunately you do not meet many people who do. Most people prefer using tools that provide a lot more assistance, making it as easy as possible to write a valid XML file following a particular XML model (schema or DTD). Some XML editors will provide more sophisticated features, but these features are more developer-oriented than the basic editor features. For this blog, let us stick with this definition: an XML editor is a software application that makes it as easy as possible to create a valid XML file, using a particular Schema...
