Download to read offline
![Vibe Coding vs. Spec-Driven Development [Free Meetup]](https://cdn.slidesharecdn.com/ss_thumbnails/vibecodingvsspecdrivendevelopment-251209105622-43f455e7-thumbnail.jpg?width=640&height=640&fit=bounds)
LavaCon 2017 - Making a Quantum Shift in Structured Authoring
- 1. MAKING A QUANTUMSHIFT IN STRUCTURED AUTHORING
- 2. Eric Kuhnen @AstoriaSoftware#LavaCon
- 3. Eric Kuhnen @AstoriaSoftware#LavaCon
- 4. Eric Kuhnen @AstoriaSoftware#LavaCon
- 5. Eric Kuhnen @AstoriaSoftware#LavaCon
- 6. Eric Kuhnen @AstoriaSoftware#LavaCon
- 7. Eric Kuhnen @AstoriaSoftware#LavaCon
- 8. Eric Kuhnen @AstoriaSoftware#LavaCon
- 9. Eric Kuhnen @AstoriaSoftware#LavaCon
- 10. Eric Kuhnen @AstoriaSoftware#LavaCon
- 11. Eric Kuhnen @AstoriaSoftware#LavaCon
- 12. Eric Kuhnen @AstoriaSoftware#LavaCon
- 13. Eric Kuhnen @AstoriaSoftware#LavaCon
- 14. Eric Kuhnen @AstoriaSoftware#LavaCon Document
- 15. Eric Kuhnen @AstoriaSoftware#LavaCon Curate Document
- 16. Eric Kuhnen @AstoriaSoftware#LavaCon Curate Document Share
- 17. Eric Kuhnen @AstoriaSoftware#LavaCon Document Curate Share
- 18. Eric Kuhnen @AstoriaSoftware#LavaCon Document
- 19. Eric Kuhnen @AstoriaSoftware#LavaCon Curate Document
- 20. Eric Kuhnen @AstoriaSoftware#LavaCon Curate Document Share
- 21. Eric Kuhnen @AstoriaSoftware#LavaCon Document Curate Share
- 22. Eric Kuhnen @AstoriaSoftware#LavaCon Training Sales Technical Support Marketing
- 23. Eric Kuhnen @AstoriaSoftware#LavaCon
Editor's Notes
- #3 Newly promoted manager of Business and Educational Services Installing a Y2K upgrade of an existing product Complete rewrite of the earlier product Technical documentation did not cover all the error codes Got the source code and rewrote the entire installation and operation manuals Gave it to Engineering, Tech Support, and to the people in my two departments SEGUE: How I felt Well, what about you Snap Survey
- #4 Snap If you ever felt complete or whole or finished or deeply satisfied when you’ve gotten it all documented And once you’re completed that project, if you ever read Marketing copy and wonder if you’re working at the same company selling the same product? If you’ve ever seen some of the stuff floating around Tech Support and you think, “But I have three pages on that stuff right here?” If you’ve ever read an RFP response and felt like yelling, “Everything these guys want, all the architecture diagrams and all of the explanations, are in the docs we’ve already written”?
- #5 The United States Department of Labor says that technical writers, also called technical communicators, prepare instruction manuals, how-to guides, journal articles, and other supporting documents to communicate complex and technical information more easily. They also develop, gather, and disseminate technical information through an organization’s communications channels.
- #6 The value we bring is much more than words and images in instruction manuals, how-to guides, journal articles, and other supporting documents. You are the Curators of Intellectual Property. According to Law, intellectual property is any product of the human intellect that the law protects from unauthorized use by others, and it is traditionally comprised of four categories: patent, copyright, trademark, and trade secrets. What do these four things (patent, copyright, trademark, and trade secrets) have in common? They are written! Someone wrote a patent application; someone submitted a written application to copyright a thing or trademark a phrase. The collected technical documentation of about the products and services built and delivered by your company are trade secrets.
- #7 Here’s the rest of the definition of Technical Writer from The United States Department of Labor: They also develop, gather, and disseminate technical information through an organization’s communications channels.
- #8 <click> Draw some circles on a sheet of paper, one circle for each department in your company that writes something. <click> Be sure to label each circle with the name of that group. Within each circle, list the format of the all the files that store these ideas, words, and images
- #9 Here’s the rest of the definition of Technical Writer from The United States Department of Labor: They also develop, gather, and disseminate technical information through an organization’s communications channels. Now, look back at your picture with the circles. If you were to mark an X between any two incompatible files, would there be a lot of X’s or just a few? In my experience, there are a lot. Go to next slide
- #10 I hope to inspire you to think about breaking through to the next level of how you see yourselves, because what you demand is what vendors will supply. Think about that: you curate the intellectual property of your organization, you have a unique calling—if you will—to disseminate that IP to everyone in your organization, and you have the power to bend vendors to your will to achieve that goal. Do you understand that last part? It means, you will not buy a product or service unless it directly and measurably allows you to Curate and Disseminate. This is the beginning of what I mean by a quantum shift in structured authoring. Let me explain how this differs from two other efforts.
- #11 Client (East coast of the United States) had two departments—technical publications and marketing—that created customer-facing content that documented the company’s intellectual property, but they used different tools Client reorganized its content creation around User Experience Which tool do you think they choose?
- #12 Prioritized easier-to-understand tooling over well-defined content structures and standard content-reuse mechanisms Notice that they’re not afraid of tagging and they want the benefits that tagging offers: content that is separate from presentation to be flexible on the output. This approach is not a quantum shift. It feels like a loss (that’s how the Tech-Docs team felt about it). It feels like a compromise (the Marketing team says, “We’re still tagging content, right?”). I don’t think “loss” and “compromise” are attributes of a quantum shift.
- #13 And then there’s the debate on the merits of lightweight-markup languages. The best and most enduring argument for these languages is SME adoption. It’s easy for them to write MarkDown content, and this gets right back the intellectual in intellectual property, that is, any product of the human intellect. MarkDown, MediaWiki, AsciiDoc…they all fit a singular purpose: putting ideas, concepts, thoughts, and descriptions into written form.
- #14 It’s the difference between capturing what’s in someone’s head <click> and conveying something from one person to another. If you go back to the US Department of Labor’s description of a technical writer, you see that it also includes disseminating technical information through an organization’s communications channels. Markdown is human-readable, but there are two keys to conveying information that Markdown does not have, such as: Purposeful structure. MarkDown has format structure (i.e., headings, indented content, lists of things), but structured languages like DITA or DocBook have content structure (i.e., task, concept, paragraph, steps, commands, etc.) representing thousands of hours debating about the best way to convey important information to the reader. Transclusion. (ESK: definition, search for MarkDown transclusion). Transclusion is content reuse within a deliberate context. Hypertext linking says that these two items are related but it does not specify how they are related. Transclusion says that this particular piece of content over here fits within contexts there, there, and there. It is the very essence of conveying information because it takes the reader’s context into account. The decision to build content with one of the lightweight-markup languages is not a quantum shift. It’s a decision prizing data over information, extraction over ingestion, capture over conveyance.
- #15 So what is a quantum shift in structured authoring? The quantum shift is recognizing the turmoil inherent in the way you now capture, curate, and disseminate Intellectual Property coupled with the insight and the determination to upgrade the experience for everyone who touches that IP. <click> If your horizon is preparing instruction manuals, how-to guides, journal articles, and other supporting documents, you’re not ready to make a quantum shift.<click>
- #16 If your horizon expands to include developing and gathering intellectual property throughout your organization, wherever it lives and in however it is built, you’re not yet ready to make a quantum shift. <click>
- #17 However, if your vision includes sharing Intellectual Property throughout an organization’s communications channels, you’re almost ready to make a quantum shift. <click>
- #18 To truly give Intellectual Property its high form of expression, you must think of dissemination, which means to scatter or spread widely, as though sowing seed; to promulgate extensively; to broadcast; to disperse. <click>When you think in terms of dissemination, you’re making the quantum shift in how we think about structured authoring.<click>
- #19 Let me tell you about a company that is making this quantum shift. Ultimate Software has 3,700 employees working very hard to build and deliver human-capital-management software as a service. They’re also working very successfully, I might add; their service generates over $780 million annually in revenue. <Click>As Ultimate Software became mature in its ability to document the company’s intellectual property, the company expanded its horizons <click>
- #20 …to include curation, which meant incorporating workflow, collaborative review, and managed reuse into their business processes. But they didn’t stop there. <click>
- #21 They used the idea of sharing to reframe their relationship with their customers. They thought, “Let’s give each customer a view into their own set of content by linking the CRM system with a new distribution portal.” At this point, their intellectual property was shared within the writing team and among the end-user community. They also saw other teams within the company who needed to reuse the company’s intellectual property to build tech-support content, training materials, RFP responses, and so on.<click>
- #22 But that wasn’t the quantum shift. Nope. <click> The quantum shift occurred when they elected NOT to force all of those departments to use the same tools and or the same content encoding.
- #23 If the Training departments wants to use PowerPoint, they get access the company’s IP inside PowerPoint.<click> Same with Sales. They use Word or maybe Outlook; they can re-use the company’s DITA content right…inside…those applications.<click> And this isn’t cut-n-paste, either. The quantum shift also means that the linkages back to the source material are maintained. So Tech Support is re-using carefully crafted, fully curated material inside ZenDesk, and when that content is updated, what Tech Support sees in ZenDesk is automatically updated.<click> Now, there’s no way you can predict how Marketing is going to spin something, but if you’re building microcontent, and Marketing can reuse that within InDesign, the quantum shift has happened.
- #24 The quantum shift I talk about today has a precedent going back some 40 years. In the 1960’s, all computers shipped with the source code to the tools they contained, and even to the operating systems that ran them. However, the late-1970’s saw the rise of restrictive software licenses and time-bomb license keys, which incurred the ire of one Richard Matthew Stallman, then a key member of MIT's AI laboratory, a firm believer in unrestricted computer access, and an unyielding champion of the idea that software should be available for use, study, distribution and modification. Do those words sound familiar to you? They should; they’re very close to the ideas we’ve examined today, that intellectual property should be created, curated, shared, and disseminated. Anyway, Richard Stallman formed the Free Software Foundation to champion the cause of Free Software. I don’t mean software that has no price. I mean software that is free to be distributed, shared, and improved in the same way that we’ve been talking about disseminating Intellectual Property to all of the people in our organizations who need to reuse it. The Free Software Foundation, and ideas the Richard Stallman promulgated then—and now—are the underpinnings of all we know today as open-source software. Talk about a quantum shift! Here’s one example: Linux, the open-source Unix-like operating system that launched in 1991, now runs more server-class machines than Windows. Here’s another: the most widely-used web-server software on the market is the open-source Apache Web Server with a 48.5% share. Microsoft’s own non-free Web Server, IIS: 10.8%. When you liberate ideas, the good ones catch on. When you liberate good software, it gets used. When you liberate intellectual property from the tools that created it, it gets re-used. That’s the quantum shift for structured authoring. That’s the path forward for your life’s work in creating, curating, and dissieminating that intellectual property. Now my friends: make it happen. Thank-you.