getting organized: practical guidelines for documentation scalability

Getting OrganizedPractical Guidelines for Scaling Your Documentation Projects

October 2014Richard Rabil, Jr.

Sr. Technical Writer

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

Opower

Our mission is to motivate everyone on earth to save energy.

3

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

Opower at Scale

» Hiring and onboarding constantly

» Multiple product lines

» Iterative development

» International clients and offices

» Specialized teams

5

6

You Get Content! You Get Content! Everyone Gets Content!

$$

Sales and Internal Staff

Utility Support Staff

Utility Technical Staff

Third-Party Developers

7

Oh Yeah, Can You Localize That?

Our Response?

8

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

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)

In a Word…

11

#SCALABILITYPROBLEMS

What Is Scalability?

“The ability of a system… to handle a growing amount of work in a capable manner...” (Wikipedia)

12

Scale happens. Proactive planning and design is the solution.

13

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

If Choices Came in Buckets...

Choices about Collaboration

Choices about File Management

Choices about Project Architecture

15

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

How Will You Organize Your Shared Repo?

17

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

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

Design Your Projects for the Future.

Choices about Collaboration

Choices about File Management

Choices about Project Architecture

20

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

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

• 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

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.)

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

Manage Your Files. Or They Will Manage You.

Choices about Collaboration

Choices about File Management

Choices about Project Architecture

26

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

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

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

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

Document it, or it never happened.

Enforce it, or it never will.

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.

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

Questions? No? Beer time.

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. http://blog.opower.com/2014/07/opower-five-terawatt-hour-energy-savings-new-hampshire.