Notes from the DITA Best Practices BOF lunch at CMS DITA NA Conference

Tracy Baker and I had a full table and intense discussion on the topics on the minds of the people in attendance. Real time issues and ideas for possible solutions. Topics ranged from reuse strategies to getting started to review processes to getting it all done while still doing your day job. Before we got started, we asked everyone to give us a little information: who are you, what industry do you come from, and what’s on your mind/what brought you to this BOF table. The participants included:

  • Erin (Telecom) who is in unstructured FrameMaker and wants to know how to planning the move to DITA (“it’s exciting and scary”). She’s also interested in contextualized content
  • Eric (Services) says he’s listening in so he can get a better sense of things
  • Cecile (Healthcare, from France) is moving to DITA from XML and she’s wants to talk about reuse strategies given that she expects that her XML modules will become to multiple DITA topics
  • Abbie (Services) is here to learn
  • Liz M (Services, Abbie’s coworker) is also here to learn
  • Bob (Medical Device) is looking for questions
  • Ed (High Tech) is also moving from XML to DITA but he wants to be sure they’re doing it for the right reasons. He’s also got a legacy data concern and seconds the request to talk about reuse strategies.
  • Renee (High Tech) is tasked with fixing a DITA environment. She wants to talk QA, processes, staffing roles
  • Moderator: Tracy Baker from F5, DITA early adopter
  • Moderator: Me, Liz Fraley from Single-Sourcing Solutions and the moderator of the TC Dojo Mastermind sessions.

Tracy Baker is a regular at the DITA NA conference. She’s from F5 and started her road to DITA in 2009. She’s an Information Architect, a writer, a tools person. She wrote the Information Model that F5 still uses today. In fact, only two elements have been added since she wrote it originally. It’s been a long road and it’s only this year, in 2015, that all the documents published for all the products have been 100% DITA. She’s worn a lot of hats but warns that “you can’t wear all the hats. You can try. You will die.”

Together, Tracy and I moderated the discussion and what follows are notes from the conversation. Tidbits, tips, suggestions, and advice for the folks at the table. One-on-one time for them to get their burning questions answered, their comfort levels…well, leveled. Continue reading “Notes from the DITA Best Practices BOF lunch at CMS DITA NA Conference”

Is your business OK with OTK?

Do you want to become a software development company specializing in customized Open Source toolsor do you buy a solution that someone else has to maintain?

By Janice Summers

I love DIY projects! I find them truly irresistible. I relish each and every facet of them. From concept to completion, there is nothing I don’t enjoy. For me, there is nothing more rewarding than seeing something I created being brought to fruition. Perhaps it is the influence from my early years and being raised in a family of DIY practitioners.

Recently I undertook a new DIY project. I needed a fairly specific type of bench / book shelf combo unit with customized features. Rather than hire someone to do it or get a readymade out-of-the-box solution, I decided this would be a perfect opportunity for a new DIY project. So I set out with an idea and started drafting the specifics of the design, selected the materials I would create it out of, and dove in. Having been an engineer by trade and training years ago, I always look forward to getting my hands into a physical project.

Now, I am not a wood worker by any stretch of the imagination but I thought, “How hard can it be?!” I have a hammer, a hand saw, a good pencil, and an accurate tape measure. Besides, I figured it would be a whole lot cheaper if I just did it myself.  Or so I thought….

Eventually I did finish the project and I did finish it on time (just in time) but I did blow the budget. The end product, even though I do like it, is flawed and not “production ready” by any means. It’s fine for the limited application I need for it and, since I am the only user, it’s good enough.

The experience got me to thinking about the correlation between building customized furniture and building company specific solutions for content creation and delivery.

Just like me, there are the DIY people out there who relish the opportunity to dig in and create their own solution. After all, there are Open Source tools out there for anyone to take advantage of. Better yet, they really don’t cost anything to use. There open for all and you think, “Hey I can save our company a ton of money?” All you need is a little ingenuity and a well laid out plan to get things rolling. Right?

Well, not so fast. You will need a bit more than just a plan drafted out. You will need some really stellar programming skills for starters. Then you will need the time, lots of time. But don’t forget, business doesn’t stop and wait for you to catch up so you may need a consultant or two or three to help you along the way.

Eventually you will get there…well, at least most of the way. You will need to fine tune your creation along the way and add features and functions because all you really got out of the initial hours and hours and hours of work was the bare bones. Then you will also need to go back and fix those little tweaks you over-looked in the beginning because the point of the tool is to have it ready for production. Of course, once you release it into the wild for others to use, in come the stream of issues and function requests. So you’ll need to start building those fun little “features” and then rolling out the new revisions. Cross your fingers that it won’t break something else along the way because that means hours in chasing the elusive “bug”.

Oops, I forgot to mention that your OTK will need to play nicely with other tools. Well, you need to spend time integrating that too. While you’ve been busy chasing the finish line, time has passed and those other tools you need to integrate with have been juiced up and, well, now you need to upgrade. Crap! Now that you have upgraded, it’s back to development because your Open Tool needs to keep pace.

Fast forward a year down the road and suddenly you realize you are on a treadmill that never stops and you never get finished. Not really. The cost in consulting fees and man hours for your company is too embarrassing to look at. Then you realize, this is not the career you signed up for so you dust off your resume and bail ship.  But hey, you got to sharpen some programming skills and that looks good on your resume. What about the company?

You see, my advice, unless you really want to become a software development company specializing in customized Open Source tools for product information, buy a real solution that someone else has to maintain and keep the DIY projects for your “Honey Do’s” on the weekend.

How to solve your Data Merge challenges

Data Merge feature in Arbortext lets you integrate live data in your content source

By David Lorenzoni

Have you ever had a need to copy information from a database report, spreadsheet or any other source into a document such as a price list or specification document only to find that once you copied the information the source of your content changed? Or even worse, you made an error?

So maybe you thought you could just cut and paste the entire spreadsheet. That might work for small amounts of information, but when the information is variable or changes frequently that might not work or it might make it difficult for the end user if the information you copied is not published correctly. And what if the data you want does not exist in a database?

This is where a very cool feature of Arbortext known as Data Merge comes into use. Arbortext lets you incorporate references to external data sources in a document, and to then resolve those references. A reference to external data is called a query and the result is called merged data. The merged data can automatically populate a document. Errors that would otherwise be introduced by re-keying, or cutting and pasting old data or incorrect formatting are eliminated.

There are also considerable time-savings through automation workflow review. One customer used Data Merge to incorporate engineering changes into the documentation so that the writers who were developing the content had the most up to date information rather than relying on outdated hand written notes. In this case, the information provided by the Data Merge feature was not used in the final output but as a starting point for the content developers.

The next time your documents or published content requires information that is already validated and maintained in another file, turn to Data Merge and eliminate errors and reduce content development time.