Documentation Tooling – Open Source Way

Technical Documentation is the backbone of open source contributions across Red Hat and Mozilla.
For Red Hat its primary for Customer Experience and Engagement for Red Hat Products.
And for Mozilla its a boon for contributors and communities.
We will learn the two different approaches to the same discipline.

This session will help you understand how Red Hat and Mozilla tool their documentation and automate it to make the lives of document writers easy.

We will walk through the process and ideas of creating tools around modular style of docs. We will also discuss the architectural know-how and what technologies are better suited to the modular approach.

The challenges & concepts of Modular documentation and why your team should move to modular docs.

Transcript

1. Documentation image credit: codehub.gr
2. Documentation Tooling Ankit Gadgil | @anknite | | Open Source way
3. Documentation image credit: mozilla.org
4. Your product needs documentation @anknite
5. Speaker Notes Developers can sometimes be lazy. Why set up React yourself when you can just use create-react-app? For that reason, your product needs good documentation. Many people dismiss documentation as unimportant, but you may be surprised to find that it can actually improve your bottom line. credits: @arthurchen_29306
6. Developers prefer product with good Documentation @anknite
7. Speaker Notes Let’s say there’s you and a competitor. Your products are both good, but your competitor’s documentation is very detailed. On the other hand, your API library only has a few lines of markup on Github. Unless your product is much better than your competitor’s, developers will generally prefer the one with better documentation. There’s a few reasons for this: It allows them to use and integrate the product more easily It reduces development time It helps troubleshooting credits: @arthurchen_29306
8. Has Adoption Impact @anknite
9. Speaker Notes Large percentage of enterprise customers considered the quality of technical documentation when making purchasing decisions. Good documentation not only helps customers to understand the product in more detail, but also allows them to estimate the development overhead required if they purchase it. Your documentation are as much a pre-sales document as they are a customer support document. credits: @arthurchen_29306
10. Reduces Customer Support Tickets @anknite
11. Speaker Notes When you already have detailed documentation on your website, customers can resolve many of their problems without having to submit a support ticket. This reduces the number of customer support tickets you receive, and means only the most important tickets will be submitted to your customer support team. For enterprise, the average customer support ticket costs ~$100 to resolve. Multiply this by the number of tickets you currently receive that can be resolved through better documentation, and you can quantify the benefit of documentation as a customer support tool. credits: @arthurchen_29306
12. Engage More with the User/Customer @anknite
13. Speaker Notes Every time you communicate with your customer, you have an opportunity to tell them something about your brand and products. Documentation is no different. Through your documentation, you can showcase: How well you understand how the customer is going to use your product Your commitment to helping the customer use the product Why your products are better than competitors How well you understand your own product Other products that might help the customer credits: @arthurchen_29306
14. Red Hat Way
15. access.redhat.com
16. Documentation Tooling
17. Pantheon
18. Pantheon I • Docs automation platform • Based on Titles, Pages and Books • Built using Python, Angular and MongoDb • Utilizes Automated jobs for AsciiDoc building
20. Speaker Notes The lifecycle of content on Pantheon 1 1. A tech document writer writes their documentation in gitlab 2. They then tell Pantheon where to find it, say by creating a metadata entry about their repository. 3. Pantheon then builds or compiles the document using automated jenkins jobs 4. The compiling process does its magic and stores metadata in mongoDB and artifacts on aws 5. The content is then delivered to the presentation layer for display on the customer portal
21. Pantheon II • The next generation Docs automation platform • Based on Modules and Assemblies • Built in Apache Sling, React and MongoDb • Houses content, previews and management
22. Management Compiling Delivery Search
23. Pantheon II • Is Open Source \o/ • https://github.com/redhataccess/pantheon • Contributions Welcome
24. moz://a Way
25. developer.mozilla.org
26. Documentation Tooling
27. Kuma
28. Kuma- MDN
29. Kuma • Powers MDN • Built in Python, NodeJs, React • Amazing Getting-started guide • Collection of Best First Bugs for contributors
31. Speaker Notes A revision goes through several rendering steps before it appears on the site: 1. A user submits new content, and Kuma stores it as Revision content 2. Kuma bleaches and filters the content to create Bleached content 3. KumaScript renders macros and returns KumaScript content 4. Kuma bleaches and filters the content again to create Rendered content 5. Kuma divides and processes the content into Body HTML, Quick links HTML, ToC HTML, Summary text and HTML • Body HTML: The “middle” of a wiki document is populated by the Body HTML. • Quick links HTML: The sidebar, on pages that include it, is populated from the quick links html. • ToC HTML: The table of contents is populated from the <h2> elements of the Rendered content, if any, and appears as a floating “Jump to” bar when included. • Summary text and HTML: Summary text is used for SEO purposes. An editor can specify the summary text by adding an id="Summary" attribute to the element that contains the summary.
32. Kuma • https://github.com/mdn/kuma • Kuma has awesome documentation ◦ Easy to start contributing to ◦ Has detailed information about best first bugs ◦ https://kuma.readthedocs.io/en/latest/
33. The Future @anknite
34. Modular Documentation?!
35. What is Modular Documentation?
36. Speaker Notes • Modular documentation is documentation based on modules, which the writer combines into assemblies. An assembly can also include other assemblies. • At Red Hat, we write modular documentation that is based on user stories. This means that each assembly documents a user story. • Let’s have a look an Architecture and concepts. • Important Nesting assemblies too deep can create too much complexity, which might make the documentation difficult to use and maintain. If you are worried this might be the case, consider linking to another assembly as an alternative to direct inclusion.
37. Module Unit Entity Self Contained Provides value
38. Speaker Notes Module on its own is: a Unit EA module is a discrete piece of content, perhaps explaining a self contained concept. The content should be capable of standing on it’s own, but written in a way that it can be effectively used in a curated list of documents (and/or glue text) such as an assembly or user generated collection. Modules are the atomic units of content, and are not nestable. They can link to one another, but will not be used as subsections of one another.
39. Module Types Concept Procedure Reference
40. Speaker Notes Concept Module The core requirement for a concept module is explaining the idea, or concept. A concept module requires a short introduction and optionally, can also include additional resources. Procedure Module A procedure module is a "do" module. It gives the user numbered, step-by-step instructions. Reference Module Reference modules provide data that users might want to look up, but do not need to remember.
41. Assembly
42. What Modular Documentation is NOT • Legacy (non-modular) documentation split into small, meaningless pieces • A collection of modules that have no relationship to one another
43. Architecture more Diagrams :D
45. Speaker Notes High Level Architecture 1. Creation - owned by content creators/documentation teams using their varied compositional tools with git/any content as a storage repository. 2. Transformation/Processing - Under the tooling space, this includes the transformation from asciidoc/etc to HTML fragments (possibly with runtime placeholders), 3. Management - Workflow management, content metadata decoration and content distribution. The interface is ideally a CDN in front of a REST platform. 4. Presentation - This is the presentation of the final content artifact, the consumers will request the content and display it on demand.
47. Speaker Notes 1. An overview of the module ecosyste 2. Aside from the number of artifacts created, there are situations where it would be advantageous, or even necessary to change or increase the available context domain without wanting to go through a republishing process. 3. Such as when a new product version is released, or product names change or are merged. 4. The lifecycle and workflow status of a module is also important to manage across module instances, suggesting that there should be an umbrella “module” concept that relates the various module instances and the variants they produce. It would be far simpler and meaningful to track the usage of the module as it pertains to the source content relative to where it ends up being used than to track only the resultant variants.
48. Module Lifecycle
49. Speaker Notes 1. Writers create modules and store them in content repositories. Similarly, they can a yaml configuration file which would contain variable names and their values (a context package) which will be used for local builds. 2. Once the platform ingests the modules and configuration files from the repository, modules will be stored in the module library, while the list of variables and values in the configuration file will be transformed into a context package in the module library. 3. Module library users would be able to create additional context packages and “tie” them to modules. This combination of module / context package will result in multiple module variants. 4. Based on parameters provided (via a url) and/or internal logic, a customer portal request for a module will result in the selection of a module, a context package, several other components (e.g. chroming, analytics, etc), and the assembly of all these components into a single html response which…. 5. The user will then consume as a single page on the website.
50. Simple Architecture Last Diagram, I Promise.. @anknite
51. Management Transforming Delivery Consumer
52. How should your tool be ? @anknite
53. Tooling • User Centricity • Insights from data • Resiliency • Future proof Architecture @anknite
54. Speaker Notes 1. staying focused on who you are building for, your tool should make the user’s life easy. 2. Good software should allow you to leverage data and draw important insights. Software must have near-cognitive abilities, making things easy to use and understand, as well as more intimate. 3. Code must be easy to change. This allows you to pivot quickly to new capabilities and add new features rapidly. 4. The product should last into the future, with an architecture that allows quick adaptations to last the entire duration of the product life cycle.
55. Thank You (: image credit: calvinandhobbes.com @anknite