Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Getting Organized: Practical Guidelines for Documentation Scalability


Published on

NOTE: *THIS PRESENTATION HAS ANIMATIONS.* It will be easier to follow if you download and open it in PowerPoint.

In rapidly-growing companies where the number of technical writers rises and the number of deliverables maintained by the documentation team grows dramatically, it becomes essential to develop a system of content management that is well-organized, consistent, and optimized to support long-term expansion and maintenance. In this presentation, I provide some practical guidelines and techniques for designing a scalable documentation project architecture in collaborative environments where growth is the norm. Although the presentation focuses on how to do this specifically for help authoring tools such as MadCap Flare, the underlying principles discussed are tool-agnostic.

What you should know beforehand:
-- What MadCap Flare is
-- What single-source publishing and content reuse are

What you will learn:
-- Why version control is essential when you have a growing team of writers
-- Practical ideas for organizing projects and folders at the right level of granularity, with team collaboration and scalability factors in mind
-- Guidelines for policies your team can use when creating reusable content such as graphics, CSS, snippets, and other resources
-- The pros and cons of various folder structure strategies and file naming conventions
-- Practical ideas for developing team-wide resources to ensure everyone follows the same standards

Published in: Technology
  • D0WNL0AD FULL ▶ ▶ ▶ ▶ ◀ ◀ ◀ ◀
    Are you sure you want to  Yes  No
    Your message goes here

Getting Organized: Practical Guidelines for Documentation Scalability

  1. 1. Getting Organized Practical Guidelines for Scaling Your Documentation Projects October 2014 Richard Rabil, Jr. Sr. Technical Writer
  2. 2. Note about Viewing THIS PRESENTATION HAS ANIMATIONS. It will be much easier to follow (and more exciting!) if you download it and open it in PowerPoint. 2
  3. 3. Opower Our mission is to motivate everyone on earth to save energy. 3
  4. 4. 4 5 billion kilowatt-hours saved $550 million reduction in utility bills 7.6 billion pounds of CO2 emissions abated 726k passenger vehicles off the road
  5. 5. Opower at Scale » Hiring and onboarding constantly » Multiple product lines » Iterative development » International clients and offices » Specialized teams 5
  6. 6. 6 You Get Content! You Get Content! Everyone Gets Content! $$ Sales and Internal Staff Utility Support Staff Utility Technical Staff Third-Party Developers
  7. 7. 7 Oh Yeah, Can You Localize That?
  8. 8. Our Response? 8
  9. 9. Challenges? No, Sir. None whatsoever. » Challengetunities • Onboarding new hires • Knowing who changed what, when, and why • Content inconsistencies • Cumbersome editorial maintenance • Content findability problems • Content duplication, not reuse 9
  10. 10. Challengetunities – Continued 10 Product 2Product 1 Product 3 User Guide Tech Brief Wiki Guide User Guide Tech Brief Wiki Guide User Guide Tech Brief Wiki Guide Author Author Product 4 Product 5 Product 13 Author Author Author Author ~250 pages per author (at minimum)
  11. 11. In a Word… 11 #SCALABILITYPROBLEMS
  12. 12. What Is Scalability? “The ability of a system… to handle a growing amount of work in a capable manner...” (Wikipedia) 12
  13. 13. Scale happens. Proactive planning and design is the solution. 13
  14. 14. Let’s Unpack That • You can no longer assume everyone is on the same page. (They’re not.) • Proactive design brings order and mitigates chaos. • At scale, small increases in time savings have significant long-term benefits. • Today’s goal: to prepare you to make proactive choices that support long-term growth. 14
  15. 15. If Choices Came in Buckets... Choices about Collaboration Choices about File Management Choices about Project Architecture 15
  16. 16. How Will You Share Files? » Shared drive or version control repository? » Examples: Git, Subversion, SharePoint » Does it really matter? » Version control: as useful as mind control, but less creepy. 16
  17. 17. How Will You Organize Your Shared Repo? 17
  18. 18. Shared Repo Organization: Practical Guidelines 18 » Draft a detailed outline » Keep hierarchies flat » Keep folder names short and consistent » Consider if a software program will need access » Add in locale folders » Ask technical SMEs about potential technical constraints
  19. 19. Why Are Flatter Folder Hierarchies Better? 19 » Pros • Shorter file paths • Less time spent hunting through many levels • Simpler choices when creating new files • Fewer folders to update if an update is necessary » Cons • Longer file lists • Less navigational aid • Fewer options for unique scenarios
  20. 20. Design Your Projects for the Future. Choices about Collaboration Choices about File Management Choices about Project Architecture 20
  21. 21. One Master Project or Many Separate Projects? 21 project-abc project-def project-ghi project-n project-jkl master-project project-abc project-def project-ghi project-n
  22. 22. One Master or Many Source Projects: Pros and Cons » One Project • Pros – No confusion over which project to work in – Easier to do content reuse and maintain consistency – Easier to update folder and file names – Better oversight of the project as it evolves • Cons – Massive number of folders and files to maintain as you grow – Could be harder to find files – Could be harder to localize – More chances to step on each other’s feet – Could have long load times for opening a project or checking files in and out 22 » Many Projects • Pros – Number of files per project is more manageable – Less trouble finding files within a specific project – Supports logical addition of new projects for new products – Fewer chances of working at cross-purposes • Cons – Complexity with content reuse across projects – Less oversight of how individual projects evolve – More chances to lose cross- project consistency – Localization still difficult
  23. 23. • directory-root • projects-src • en_us • bdr • csi • global • uua • wami • wami.flrpj • fr_fr • bdr • csi • global • uua • wami • wami_fr_fr.flrpj Locale Project folders based on product acronym How Will You Organize Your Projects? 23 » Practical guidelines: • Use a flat list and acronyms for project folder names • Design for localization and/or release versions • Within these broad guidelines, find the scheme that works best for you
  24. 24. How Will You Reuse Common Content? » Scalability Considerations • Write guidelines about what goes in global vs. child projects • Be careful about renaming global files • Beware of child project explosion 24 project_a project_b project_c project_n global_project » Global CSS » Global images (logos, screenshots, etc.) » Global topics (procedures, overviews, etc.) » Global snippets (copyright statements, etc.) » Global variables (product names, company name, etc.)
  25. 25. How Else Will You Save Time and Maintain Consistency Across Projects? » For example, will you… • Use information models? • Use variables and variable sets? • Use TOC templates? • Use templates for topics and targets? • Write team-wide guidelines? 25
  26. 26. Manage Your Files. Or They Will Manage You. Choices about Collaboration Choices about File Management Choices about Project Architecture 26
  27. 27. How Will You Organize Sub-Project Files? 27 » Some are already well organized » Avoid more than two folder levels if you can » Weigh the pros and cons of different schemes • By procedure, concept, or reference • By main sections of a document • By main features of a product • By product name • By locale code • By deliverable type • By audience » Example: by main sections and product » Hate folders? Experiment with tags
  28. 28. How Will You Name Your Files Consistently? » Initial Caps and Spaces • About Your Energy Use.html • Data Requirements.html • Downloading Your Report.html • Updating Your Home Profile.html » Codes, Prefixes, or Suffixes • smb_Data Requirements.html • smb_Downloading Your Report.html • wp_About Your Energy Use.html • wp_Updating Your Home Proile.html » Dashes • About-Your-Energy-Use.html • Data-Requirements.html • Downloading-Your-Report.html • Updating-Your-Home-Profile.html 28 » Underscores • About_Your_Energy_Use.html • Data_Requirements.html • Downloading_Your_Report.html • Updating_Your_Home_Profile.html » Camel Case • AboutYourEnergyUse.html • DataRequirements.htm • DownloadingYourReport.html • UpdatingYourHomeProfile.html » Hybrids • Camel Case + Prefixes – smb_DataRequirements.htm – smb_DownloadingYourReport.html – wp_UpdatingYourHomeProfile.html – wp_AboutYourEnergyUse.html • Prefixes + Dashes + No Caps – smb-data-requirements.htm – smb-downloading-your-report.html – wp-updating-your-home-profile.html – wp-about-your-energy-use.html
  29. 29. What’s in a (File) Name? 29 The most annoying message in the universe:» Name Length » Name Readability » Name Consistency / Scannability » Technical Constraints » Recommendation: Different Conventions for Different File Types Do Something Like This • About Neighbor Comparison Module.html • Web_Portal_Customer_Service_Guide.pdf Not This • NC Module.html • WP_CSR_UG.pdf
  30. 30. Document Thyself 30 » Use a web page, if possible, to aid browsing » Use color coding » Show lots of examples » Use alphabetical organization » Use different categories of conventions
  31. 31. 31 Document it, or it never happened. Enforce it, or it never will.
  32. 32. Closing Thoughts » Scale happens. Proactive planning and design is the solution. » Collaboration: The needs of the many outweigh the needs of the few. » Project Architecture: Design for the future. Be highly detailed. » File Management: Manage your files. Or they will manage you. » Document. And enforce.
  33. 33. In the end, how we plan and design for scale is an extension of our art. “Engineering is not science, it is an art, and there is always a wide range of choices in how to solve engineering problems. An engineering designer ‘signs’ his work by those choices just as surely as a painter does.” ~Robert Heinlein, The Door into Summer
  34. 34. Questions? No? Beer time.
  35. 35. Sources » Tinjum, Aaron. July 22, 2014. We’ve now saved 5 terawatt-hours. That’s enough energy to power New Hampshire for a year. Accessed Sep 23, 2014. hampshire.