by Søren Weimann | Mar 22, 2021 | Blog
A review can be a complex thing to manage. And when you have component-based content and reviewers who want to review the full document – let’s be honest, most of us do – then the process of getting the approved review comments back into your components can be a very time-consuming task. So, there is a lot to gain by streamlining and automating this process as much as we can… without losing full control. With the new features in Dx4 called Compound Doc Publishing and Sync Components, we can take major steps in reducing complexity, saving time and manual effort. Let’s break the process down into five steps – well actually three of them are not much more than clicking a button or two… and getting coffee. The goal of the review is to have a component library in Dx4 that is up-to-date at the beginning and end of all review cycles. This allows us the security of having a full version history for each cycle and allows to repeat the cycle as many times as needed. In order to achieve that, we really only need two roles: A Content Architect that knows his way around Dx4 and can kick off the review and sync the results back to Dx4.A group of subject matter experts (SMEs) and other reviewers that are responsible for the content to be current and correct with their expert knowledge. To complete a full review cycle there are generally five steps to complete, and only two of them involve the SMEs: The Content Architect publishes the relevant components into full Word document.The Content Architect makes...
by Søren Weimann | Mar 1, 2021 | Blog
Writing in full documents is preferred by most authors who are not used to component-based content. And with the Sync Components feature in Dx4, this is now possible to do this in a component-based solution – without all the manual work of replicating the changes in components. You can simply use the updated full document to automate the updating of components.But what do you do when parts of the document are reused across multiple documents? Do you want to risk the updating of content messing with already approved content in other documents? Of course not!That is why the Sync Components feature comes with flexible synchronization that allows you to protect any topic in approved state from unwanted changes. Let’s go over how to approve reused components and ensure that they are not updated when syncing components from a Compound Document. We will start with three document models that have a few components that are reused across all documents, and some that are specific to each document. I’m doing set of small country specific manuals for an international bank. Let’s focus on the documents for Australia, Ireland and the USA. Components in a red frames are reused across all three documents. They are centrally authored and approved before the country specific versions will be authored. The two remaining components in each manual are country specific. Let’s start out making sure that single sourced components are correct. We will have them reviewed and approved. In DxNavigator I can approve an individual component by right-click it and selecting Approve Node. Once approved, the component icon will appear with a green checkmark in...
by Søren Weimann | Jan 22, 2021 | Blog
I think we have all been there. I know I have certainly asked people to review and comment on a few topics og content components, only to be confronted with the fact that context is needed. Well, even though I have been working with components for more than 15 years…to be honest, I have been doing updates of components myself and realized that I need more context to do a proper job. And sometimes it is bit of a clunky process to open or preview one component at a time from a map editor. So this has left me with two choices: I can provide the full document on the side, and ask the reviewer to update the componente while getting the context from the full document.Or I can provide the full document, and tell the reviewer to forget about the components. I’ll just ask the reviewer to write comments and amend the full document. None of these solutions are ideal. If I go with the first solution, the reviewer will have to jump back and forth between the component and the full document. That will be a pain for the reviewer. If I go with the second solution I am left with the job of having to update the components myself when I receive the full document from the review including comments and changes. This is time consuming and prone to error. Fortunately, this problem is nolonger there. Now there is a third option. Now I can actually provide the reviewer with a full Word document for commenting and updating, and I can automate the process of getting...
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 | Sep 16, 2019 | Blog
DITA XML makes advanced content development and management possible, but DITA XML itself is a complex thing. For some, this complexity makes DITA XML inaccessible, and for others, the complexity over time becomes a chaotic cobweb of references and dependencies. Just looking at all these tags and attributes scares some writers off. In a recent survey, we uncovered strong indications that the complexity of DITA XML is hindering the spread of structured writing across departments. For this reason, we created the Open DITA Manifest to make a framework that allows other ways of achieving some of the most important benefits of DITA XML, even for those who do not want to work with the complexity of XML. Open DITA is meant to allow everyone access to the power of structured writing. Open DITA is not a specific set of DTDs like DITA XML. It is a set of functional features in a content authoring and management solution. Any solution that can be said to make these features available, is an Open DITA solution. So here it is… The Open DITA Manifest To comply with the Open DITA Manifest, a solution: CAN use a topic persistence format different from DITA XMLMUST comply with the rules presented below. Rules DITA map supportContent references (conref)Content types: Minimum Topic, Task, Concept, ReferenceGeneralization to generic DITA topic supportedDITAVAL supportSupport for semantic taggingImport DITA XMLExport DITA XMLSupport automated processingSupport styling, layout and formatting through a standard styling language Examples of Potential Open DITA solutions DITA with DOCXDITA with HTML5DITA with JSON Open DITA is not competing with DITA XML. We consider Open DITA to be an extension...