In this guest-penned blog entry, Club Car’s Eric Petzoldt shares with everyone some thoughts that he documented following his company’s transition from DocBook to DITA (in 2016). He hopes, as we do, that this information might be beneficial to you as you continue your own march toward technical information dominance.
Club Car’s Eric Petzoldt shares with everyone some thoughts that he documented following his company’s transition from DocBook to DITA (in 2016). He hopes this information benefits your own march toward technical information dominance.
Read Entire ArticleDo you remember the pain of having to try to make your documents look nice (and look the same as your other documents) using desktop publishing software? Not fondly, we bet. The ability to separate your content from the format is the gift that keeps on giving, and the ease of data development and entry in a basic, structured environment saves so much time and effort.
Corporations and institutions that have invested time and effort into building and improving technical data specs over the last few decades definitely deserve our thanks. IBM (DITA), ASD (S1000D, STE), ATA (iSpec) and others have not only built these data structures to ease the pain of data development and management, but made them accessible to the masses as well. Big ups.
If you’re working with structured content (i.e., XML) you have a lot of options for creation, management and delivery of your content. Because XML is an open standard you can utilize best of breed components that will likely work with each other at a sub-document level and allow you to deliver print, PDF and HTML5. This reduces creation and translation costs while also reducing your time to market. Most importantly, it allows you to improve customer satisfaction by delivering the right content to the right consumers when, how and where they want it.
How great is it to meet other people who are in the same boat as you, working on the same types of projects? Even if you completely avoid the conference vendor tables (SHAME!) you can learn so much being around and engaging with your industry peers. Regional and local forums can also be a great place to interact with other tech writers and managers, often times without a vendor hall and sometimes with no salespeople around at all! And, if all that weren’t great enough, people throughout the techcomm industry are tripping over themselves to share and post great information via their webinars and blogs. How did anyone ever get anything done before the Internet?
One seemingly unintended (positive) consequence of the industry’s move to structured data is the ability to focus on the end user and continually expand the ways that they are able to view your content. There are more ways than ever to get your content in front of the people who want (or need) it, and that increased availability comes full circle when you are the end user of another company’s content.
One big aspect of the end user experience is accessibility, and the tectonic shift that has taken place in the mobile realm over the past few years has made it easier than ever to access massive amounts of data by pulling a device out of your pocket. Someone somewhere in the world needs the content that you are developing, and it should make you feel good to know that they can access it whenever and wherever they need to.
If you haven’t had the opportunity to be thankful for one or more of the items on this list, JANA can help. We offer a number of services geared toward helping companies evaluate and improve their technical documentation systems and processes. So if you see something on our list that you’d like to be thankful for this time next year.
Being a technical information manager during the transition to a new system or specification can be scary especially if you find yourself in a nightmare scenario with a bunch of unknowns lurking around every corner.
Read Entire ArticleIt’s easy to get caught up in the use of technology to solve our business problems. In the world of technical communication and field service there have been significant technical innovations to improve efficiency and reduce costs. XML has made the concepts of content reuse (using the same ‘chunk’ of information in multiple instances) and content re-purposing (having the same information output in multiple formats – PDF, web, etc.) available to organizations of all sizes. Mobile devices have allowed field techs to quickly access the information that was once found in large books and parts catalogs. The Internet of Things (IoT) promises to make predictive maintenance a reality.
Good project management always includes a thorough postmortem of the project: what went well and what could have been done better. Lessons learned. A frequent refrain is not that the technology was ‘good’ or ‘bad’ but rather how the human side of the process was managed. Organizations competing in today’s rapidly changing technological markets are faced with the challenges of “dualism”–operating efficiently in the present while innovating effectively for the future. Managers and leaders within these organizations not only have to focus on current market success and profitability, but they must also introduce the next generation of technical advances, product attributes, or service features that will sustain and even augment their continuing global competitiveness.
You may want to read “The Human Side of Managing Technological Innovation: A Collection of Readings” by Ralph Katz (MIT). The book provides a collection of articles that increase the sensitivity and understanding of individuals who are managing or influencing innovation and change processes within organizations. It also offers practicing managers and staff professionals new ideas, tools, and insights for problem-solving, organizing, and functioning more effectively.
An aircraft required a High Pressure Shut-Off Valve (HPSOV) replacement on an on-wing engine in a line maintenance environment. The Technician assigned to the task started the work at the end of his shift and was able to remove the valve and prepare for the installation. The Technician used the accepted Aircraft Maintenance Manual (AMM) procedures for the removal, which had included the removal of four clamps to loosen adjoining ductwork to facilitate the removal. The two clamps not directly attached to the valve are located underneath adjacent ductwork, and components and are hard to get access to and were not easily seen. The ductwork and valve are a close tolerance, rigid fit and the valve and ducts remain in place without the clamps. The Technician left the work with the valve in place and the clamps uninstalled.
The status of the work was provided to the Technician on the next shift. The Technician assigned for the installation of the valve had performed the removal and installation on several occasions and used a method he learned from other Technicians that did not require the removal of two of the clamps not directly connected to the valve. This procedure deviated from the AMM.
At the start of the installation, the second Technician noticed there were four clamps, two which were in better shape than the others and made the assumption that the newer looking clamps were ordered as replacements for the others and that the other two were left installed. The second Technician did not notice the clamps missing from the installation. The Technician installed the two easily-accessible clamps connecting the valve to the ductwork, secured sense line, electrical, closed the cowl and signed off the log.
The aircraft was dispatched for flight. Following takeoff, the aircraft experienced a fire warning and immediately returned to the airport declaring an emergency. The subsequent investigation revealed that the unclamped segments of ducting separated under takeoff pressure, allowing unrestrained high pressure, hot compressor bleed air inside the cowl.
When deviating from the AMM, not only are the engineering considerations overlooked, the method to provide the partial status of a task has also been compromised.
When the Original Equipment Manufacturer (OEM) writes maintenance procedures they may understand the engineering requirements driving the procedure the procedure; but do not always understand the environment the Technician works in and may not have the same experience level in maintaining an aircraft. That being said, through proper technical vetting with engineering approval, operator experience can be applied to the procedures.
Engineering and reliability can also be affected when approved procedures are not followed. In the above situation, the valve was installed using the engine duct flange as a fulcrum to pry the replacement valve in place. The results of the stress on the flange or duct after a series of valve removals and replacements are unknown; however they could show up in a future inspection as a latent failure or possibly as a worst scenario.
To ensure consistency in the application of these procedures, the use of aircraft publications must be mandated by the operator as the standard and deviations must be approved and incorporated.
Maintenance induced errors emanating from inconsistent procedures that deviate from the approved standard can make it difficult to determine the corrective action to a reliability problem. Following approved procedures is mandatory and when they are complied with, procedural changes can be made and reliability trends can be correlated more consistently to the revised practices introduced through the revised procedure.
Recently, Keith Schengili-Roberts and I presented a webinar on the importance of DITA short descriptions. As an advocate of short descriptions I have posted on the subject a few times in the past. The webinar, which summarized those postings, was well received.
Besides reviewing best practices for writing short descriptions, we discussed how effective short descriptions are an opportunity to help users easily find the correct information for which they are looking. Satisfied documentation users lead to satisfied product users. Satisfied product users lead to good product reviews. Good product reviews lead to good sales numbers.
In putting the webinar together, Keith pointed out another important reason for using short descriptions that I had neglected in those posts. His point is that short descriptions appear within search engine results. An effective short description is important to enhancing search engine optimization (SEO).
SEO is the process of improving the rank a site or (in the writer’s world) topic has on a search engine result page (SERP).
Searching on “build manifest feature” resulted in the SERP shown above.
Of the three results, which do you think you would click? Manifestly (sorry), it would be the first. It tells you right away that this article knows what a build manifest is. The second result is a poor short description because it simply repeats the topic title. And in the third? Well there is NO short description. No telling what you are going get there.
The fundamental ‘selling point’ of DITA (Darwin Information Typing Architecture) XML is the concept of content reuse. The idea of having a small ‘chunk’ of content that is stored in one place and used in many instances. Content reuse can dramatically decrease the actual amount of content that the technical publications group has to manage and significantly increases the quality of the content (because the same idea is stated the same way always).
Soren Weimann has a video explaining the idea of content reuse in DITA using Lego™ blocks (which represent individual topics), paper outlines of Lego™ blocks (maps), a bowl (to represent a Content Management System) and a camera (to illustrate output).
One of the oft-cited challenges of implementing content reuse is that it’s so hard to actually do. Many of the organizations that have implemented DITA have very little (or none) content reuse. It’s typically viewed as a future enhancement that hasn’t been implemented yet.
We often hear “It’s hard to find similar topics” from those that are having difficulty implementing reuse.
A comprehensive metadata strategy would go a long ways to help implement reuse. So what is metadata and why would a metadata strategy (and taxonomy strategy) help?
Metadata is information about your content. Think of it as the label on a can of content.
Without having to open the can you can know a lot about what’s inside. Ingredients, directions for use, nutritional information, related recipes, etc. – it’s all there on the label. Think of the label as a collection of metadata. It’s not the soup, but it tells you a lot about the soup.
Now imagine if that data was organized in a manner that would allow you to search on it – classified in ways that were useful to readily find the information. For a can of soup the label strategy includes information about the soup (ingredients and nutritional information), how to use it (directions for use and recipes) and who made it.
Metadata in a DITA setting allows you to know a lot about the topic without having to open the topic. It is a key component of enabling content reuse because – if implemented correctly – it makes it easier to find similar topics.
Imagine a scenario where your company is developing the SuperWorks 300. It’s based on the SuperWorks 200 but has improvements in the electronics that allow it to communicate with a remote controller, including the capability to update the integrated software remotely. Much of the technical information for the SuperWorks 300 is identical to the relevant parts of the SuperWorks 200, but you need to pay close attention to the electronics aspects of the technical information to make sure that you’re providing the right information for the SuperWorks 300. Finding the relevant topics that you may be able to reuse segregates your content into two categories: information that you already have (from the SuperWorks 200 or otherwise) and areas you’ll need to work with Engineering to create new content.
In a similar manner to a soup label, a metadata strategy for technical content topics may include information about the topic, what product it’s applicable for and who created or revised it. A good metadata structure is a mix of the obvious and intuitive. Not only is a good idea of what you have important, there also needs to be a solid understanding of the direction the organization is headed to try and best address future needs. A successful strategy should be based on discussions with writers to understand the current process and the perceived shortcomings.
Metadata strategy is a constantly evolving process as product lines evolve. Criteria that was unknown five years ago (e.g., IoT sensor capability) may be critical now. Criteria that was paramount twenty years ago (e.g., uses Freon-12 ) may be obsolete.
Our experience is that full text search is not a useful metadata strategy because there are too many false positives.
Extending metadata into and outside of the enterprise not just for content reuse– it also supports end users searching your content to find that needle in the (content) haystack. Examples include supporting a faceted search on a website, retrieving a repair topic based on diagnostic codes or serving up content based on product feature.
Amazon uses metadata to help you zero-in your search to help you find (and buy) exactly what you are looking for. A search for “solar panel” allows me to narrow my search based on:
Related to metadata is Taxonomy – the practice and science of classification. The basic idea behind taxonomy is to provide a controlled vocabulary for metadata attributes, and to specify relationships between terms in the controlled vocabulary. Taxonomies allow a search for one thing and have results that are related to that thing – automatically. If you use Amazon then you’re probably familiar with the concept of taxonomy. Selecting a hammer will also show results for items that are related to a hammer.
Screwdrivers and tool bags have a similar classification to hammers and an interest in one may lead to an interest in another.
A thoughtful metadata and taxonomy strategy can be a critical aspect to implementing a viable content reuse strategy. Investing the time to standardize the vocabulary and identify the “Five Ws” (Who, What, Why, When, Where) go a long way to helping find similar topics.
In this blog entry, JANA Senior Business Analyst Jeff LaFontsee uses his decades of experience to illuminate a Federal Regulation that is wide open to interpretation.
Read Entire ArticleI noticed a graphic from Dez Blanchfield who was speaking in May at CeBIT Australia (a technology & business expo). He posted this slide.
You can add another: Largest publisher of information in your company doesn’t publish books ( Technical Publications )
The Digital Disruption has already happened to the collective industry known as Technical Publications. Which means it is happening at nearly every company this industry serves.
Lisa Arthur wrote an article for Forbes in March 2013 titled “Five Ways Digital Disruption Will Impact The Customer Experience” and two of her five were ‘Personalization of interactions’ and ‘Speed of interactions’.
Those that consume technical information (engineers, technicians, mechanics, support staff, etc.) are looking to quickly get the nugget of information that they need to do their job safely and efficiently. They want to know that the information that they access is relevant for their task at hand (Personalization) and they zero in on a procedure, specification or other nugget very quickly without having to sort through manuals and pages (Speed).
Offering a directory of PDFs that use a Table of Contents navigation may be a fine last resort – but make no mistake – it should be a last resort. Lisa Hoover at MindTouch wrote a brilliant blog post in 2013 titled “5 Cold, Hard Truths About PDFs as Product Support” where she outlined some of the main reasons why PDF is not a good solution for technical information.
In some situations you have to deliver the entire manual – for legal and/or off-line aspects. You should definitely have that capability for archival purposes. But the entire manual is typically not what your customers need for day-to-day usage.
In subscribing to the adage “let the requirements drive the solution”
This doesn’t get into the aspects of content creation, translation and integration with other systems and/or manuals.
Maybe that’s a post for another day.
Are you delivering ‘manuals’ or ‘information’?
What do your customers (internal and external) want?
In a previous post, I talked about the history of DITA and how it came to be. And while the post received a number of likes and comments, it was from a birds-eye view.
A colleague of mine, Keith Schengili-Roberts, recently published two excellent articles on the birth of DITA in which he interviewed two of the people directly responsible for DITA. I would be remiss as an amateur historian if I didn’t post links to these articles that take you directly back to the time that gave birth to DITA via the memories of Don Day and Michael Priestley. Don and Michael will also talk about some of the other folks that brought DITA into the world.
The iconic "JANA Man” emblem was brought to life by JANA’s founder, Joseph A. Niland, to embody his global vision for the company. The original design featured the entire globe nestled within the figure's torso, symbolizing the company’s worldwide reach (literally, JANA around the world!). In early 1978, it was reimagined into the distinctive image seen today; and recently, it was subtly updated to include a notch in the figure's head, mirroring the ball in the JANA logo.
This evolution of the "JANA Man" represents the company’s enduring mission: to connect across continents, expand its business continually and leave a lasting global footprint. The JANA Man is more than just a design; it's a testament to the company’s ongoing journey and commitment to global excellence.
Need more information? JANA is here to help!
Contact JANA Today