Small Teams | Big Impact

1. Small Teams | Big Impact A collection of practical reminisces from two documentation writers

2. Who we are Shahida is a Lead writer at Vocera Communications. Some of her stints include Brocade Communications, Juniper Networks, and Symphony Service in a career that has spanned over 15+ years. Her expertise is in setting up end-to-end documentation eco-system, establishing documentation Best Practices, Content Strategies, and Project Planning. She believes in collaboration, clear communication, and optimism. For Moi, it has been over 12 years of joy in discovering and perfecting the art of technical documentation while donning a variety of hats ranging from Principal Writer, Documentation Lead, Project Manager, Team Lead, Content Strategist, and XML Architect. She is currently the Team Lead in India for the A10 Networks team that she helped build from scratch. She believes work is fun when you have a passion for it, and that teamwork supersedes and augments individual brilliance.

3. Agenda "The time has come," the Walrus said,"To talk of many things:Of shoes--and ships--and sealing-wax--Of cabbages--and kings-- By Lewis Carroll

4. A Welcome E-mail to a Start-up Project The pool is warm, jump into the party!

5. Anatomy of an Organization

6. Lean Innovation A delve into the qualities that makes innovation easy

7. Ambiguity is an Opportunity • Offer choices— Always have a plan B to combat resource and cost issues. • Be open and curious— Do not be afraid to seek and reason about the inherent problems that have been lingering around for a long time. • Skill development— Your organization pays for training and skills development. Sign up for at least one course a year. • Question the status quo—Just because something works fine does not mean it cannot be made better. • It needn’t start with a bang—Change does not have to be monumental. Take one small step at a time. • Why fail when you can Pivot —Pinterest was once Tote, a window shopping company.

8. Thought Leadership The glue of a highly successful team

9. Relating to your Manager • Take time to understand your manager as a person. • Understand the reasons and motivations required for the work you do • Focus on tasks that matter to the organization goals. • Your manager is also a person and subject to good and bad days. • Time your ideas and present it at the right opportunity. • Be positive even while you complain. • Don’t present problems, brainstorm for solutions. • Not flattery, but compliment your manager when a job is done well. • Don’t be afraid to ask your manager about how you can help in the team’s pain points.

10. “Most great learning happens in group. Collaboration is the stuff of growth. By Ken Robinson Relating to your Peers • Recognize the fundamental right to dignity and respect that every team member has. • Cherish a culture of appreciation. • Disagreements will happen, work for compromises. • NEVER email during a difficult situation, call for a 1X1. • Always wear the shoes of the other person before making a judgment. • It does not have to be a mistake when it can be a learning opportunity. • Ask your colleague to teach you something. • Don’t hoard information; brainstorming works much better.

11. Next-Gen Docs Preparing for the next 20 years and thinking beyond HTML and PDFs

12. The Next-Gen of Documentation

13. Sample Documentation Projects • Automated PDF and HTML builds for highly personalized deployments. • Personalized log-in portal for customers. • Intuitive software workflows with integrated example tasks. • Vibrant documentation templates—moving away from the Enterprise black and white. • Better website and documentation designs for easy information retrieval. • Multi-pronged customer feedback research capabilities. • Branding documentation as a solutions entity for customers.

14. Personalized Portal– Amazon

15. New Skills for Documentation Teams • Machine Learning • Gamification Theories • Analytics • Data Mining, Analysis, and Modelling • User Experience Design • Automation

16. Open-Source Tools Flexible, powerful, and free-of-cost

17. Getting the Best Bargain Characteristics of a good documentation setup: • Reusable content • Separating content from form • Version control system • Multiple publishing formats • Multiple authoring environments • Interoperability with other authoring formats

18. The Three Queens of Content Tools • DocBook– A DTD in mark-up language with a wide array of publishing options. • AsciiDoc-- A simplified mark-up language based on plain text. Files can be converted to HTML and DocBook and from there to other output formats. AsciiDoc can be converted using pandoc or AsciiDoc commands. • Sphinx– A Python-based software that uses the simplified markup language reStructuredText (reST) to generate different file formats.

19. A Peek into DocBook • An opensource schema for XML or SGML mark-up language. • Encourages reuse by using XIncludes and olinks. • Requires an authoring tool such as GNU emacs and a publication tool such as xmlto for converting the files to various formats. • Very powerful, but may scare off many first time writers with its staggering rules for tags and syntax.

20. DocBook Sample in Oxygen

21. A peek into AsciiDoc • AsciiDoc belongs to the family of lightweight markup languages, the most renowned of which is Markdown. • Convertible to DocBook for multiple publishing formats. • The Asciidoctor processor parses the document and translates it into a backend format, such as HTML, ePub, DocBook or PDF. • Content chunking is achievable through sections and files. • Supports conditional blocks. • Less cluttered with tags makes an easy read of the contents. TRY: https://asciidoclive.com/edit/scratch/1

22. AsciiDoc Sample

23. A peek into Sphinx • Currently Sphinx supports Python, C, C++ and Javascript out-of-the box and Java (and other JVM-based languages) via javasphinx. • Sphinx uses a Rest parser such as docutils to publish multiple formats. • The conf.py file controls the settings of how your output looks and it can be tweaked endlessly. And now for a demo

24. Interested? Here’s how to dive-in • Identify a small-scale documentation project. • Make a choice of any one of the free authoring tools as well as a version control system such as SVN, Git, or Mercurial. • Set up your authoring environment. • Do some test runs with some portions of the text, working with chunking, cross-references, images, tables, codes, and so on. • Modify the style sheet to meet your branding requirements. • Publish the full document. • Test, Rinse, Repeat.

25. References • DocBook, AsciiDoc or Sphinx – Choices, Choices…! A Comparison of Document Formats by Janina Setz at https://www.suse.com/c/docbook-asciidoc-sphinx-choices-choices-comparison-document-formats/ • Sphinx Homepage at http://www.sphinx-doc.org/en/stable/ • Documenting Your Project With Sphinx at https://youtu.be/L-fXOoxrt0M • What’s One Thing Startups Can Teach Big Companies? At https://articles.bplans.com/whats-one-thing-startups-can-teach-big-companies/