Getting Organized: Practical Guidelines for Documentation Scalability
-
Upload
richard-rabil-jr -
Category
Technology
-
view
504 -
download
0
description
Transcript of 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.