Documentation Project Management

Editor's Notes

• #5: Requirements = expectations … .of the customers (audience) who’ll use the documentation … .of the company or client that’s producing the documentation Requirements should be based on a needs analysis: Who’ll use the doc? What results will they expect to achieve with it? They should be spelled out CLEARLY and COMPLETELY – it’s your job to see that this is done You’ll have limited resources – make sure you’re delivering exactly what the client wants, no less but no more Don’t get to the end of the project and find out that you didn’t deliver what was expected Assign people and resources – who’ll do what, with what, at what cost Control the process (the plate spinner) There are all kinds of metrics and analytics – What will you measure? (earned value) Each work item (task) in the process should return a certain value: added revenue or (more likely) cost avoidance What’s the ROI for this task? If it doesn’t return value, don’t do it Measure and track as the project goes along Respond to (inevitable) change Analyze and report the results: report up, down, and all around
• #6: The documentation plan (doc plan): It’s central to all that you do It guides the whole project, like the North Star You’ll refer to it throughout the project It spells out exactly what’s required, so that expectations are well understood It’s a contract between your team and the rest of the stakeholders “Here’s what we’re going to deliver, when, and for how much” “Here’s what we need from you”
• #7: The doc plan: Describes the product, ideally in terms of user stories (more about those later) Describes the audience for the documentation Describes the information to be produced (the design and architecture) Example: Context-sensitive help; printed install guide; user forums Says who’ll do what, when, and how much it’ll cost Describes your team’s dependencies (contingencies) on others Describes assumptions: the ground rules – we’ll use FrameMaker 9, the AP Style Guide, etc. etc. Contains schedules and checkpoints Again: The doc plan is your guiding star
• #8: The doc plan sums up everybody’s expectations for the project Therefore as a writer you should know what the Doc Plan says about: Your own work assignment The tools and processes you’ll use Editorial and style guides How much money you can spend The doc plan guides your day-to-day work It gives you a compass: If you see things going off course, you can raise a flag It tells you how the process is supposed to work, so that you can speak up when you see that it isn't working.
• #11: The traditional process works something like this: Many months to develop a product and its doc There’s going to be a product – we decide what the documentation will be: One way communication: My company publishes the info, the customers consume it The doc doesn’t change: it’s static, and it’s official (because it has the company logo on it) We write a doc plan, which is also unchanging and “official” We spend a lot of time gathering info: first to write the doc plan, then to write the documents themselves (Lt. Columbo) Write/Review/Edit – probably repeat a few times Then, at the end, publish everything
• #12: Here’s how the process is changing: Development cycles are a lot shorter The monolithic plan is now broken into a series of short-term plans (Not a bad thing: remember, in the old process, I said that change is inevitable anyway) No more static, official, one-way communication It’s replaced by a two-way dialog: information comes in from the community (the users), not just out from your company Content gathering becomes collaboration The writer might be more a “curator” of content from all over (Marketing, Engineering, Tech Support, customers) than a writer of content Writers live with the developers (esp. in Agile) They have to – it’s the only way to keep abreast of what’s happening on the project You might publish multiple times, rather than just once at the end of a long process That might even mean that content isn’t perfect when you ship it (come back and fix it later)
• #14: Here are two questions that might come to mind, if you’re a documentation project manager: For Web 2.0 Content is flowing to and from customers From other parts of the organization How can I keep track of – much less control – the flow of content? How can I plan the work when I don’t even know what the content will be? For Agile What does it do to my doc plan? I tell my students that the doc plan is sacrosanct: It sets forth all of the requirements for the product It details all of the content that will be developed But in Agile…. The exact contents of the product aren’t known at the beginning of the project User stories (requirements) can and do change frequently What happens if requirements and expectations are changing throughout the process? Notice that these questions are similar to each other For example, a detailed doc plan assumes that I can track and control the content
• #15: The early Web (“Web 1.0”) was a one-way medium People put stuff out there for other people to read eCommerce figured out how to interact with users, but publishing remained a one-way process People consumed the information we published, but they had no ability to influence it or contribute to it Web 2.0 takes us beyond publishing, to participation Collaborative forms of developing information User-generated content (UGC) comes into play User-generated content can be folded back into the “official” docs and published at the next interval More important, the user community sees this content as equal to – if not better than – the “official” content Content reflects what real users think is important – not what an SME thinks is important
• #16: Example: Adobe Community Help Adobe describes it as “an online service for instruction, inspiration, and support” Adobe uses a Google-based search engine Finds information in Adobe’s own documentation & web-based help As well as in forums and other user-generated sources Notice in this screenshot The top search result is a forum entry – content that came from the community The next search result is a company-produced help topic ACH is still in its early stages It remains to be seen whether the community will be a reliable source of content But it has a lot of promise And Adobe has made it very approachable: It’s easy to use, easy to contribute Content is easy to find
• #17: Anne Gentle points out that communities don’t just happen The community has to be nurtured and managed It’s not “if you build it they will come” Technology alone won’t change people’s behavior Most people aren’t as eager to contribute content as, say, you or I might be Someone needs to breathe life into the community and nurture its growth How do we do it? Here are a few ways (but I think there are more waiting to be discovered): Invite contributions to participate – you might need to stir the pot Look how Adobe chose the word “inspiration” Make it easy to contribute Provide a structure (e.g., template) that invites participation (and makes content easy for your to process) but which isn’t too stifling Make user-generated content prominent: Feature it on your site & in your search – like Adobe Community Help Don’t make UGC subordinate to your “official” content Anne Gentle describes a new role: the community manager Someone who builds the community by helping each contributor find his or her place in the community… … .and by providing tools and processes to expedite contributions
• #18: C haracteristics of a documentation project in Agile: Small teams that work closely and meet frequently (usually every day) The meetings are known as scrums – which as any rugby fan will tell you are NOT chaos but are actually highly organized The writer “lives with” the SMEs rather than reading an engineering spec and then asking for reviews Experience is teaching us that this is a good thing As PM, you need to stay closely connected to the project… … and ensure that your writers are included on the scrum teams Comprehensive doc might take a back seat to “just in time” doc Prioritize the information that the customer needs most… … .And which pertains to the specific piece of software being developed Goodbye to the idea of a writer sitting down and writing a book Now each writer writes a set of topics, and the topics are assembled as needed Dangers: No one has the big picture in mind Inconsistent style, terminology (because many different writers are in the mix) I’ll talk about these in more detail later
• #19: Agile emphasizes including the customers in the development process Product development is based on user stories “ I am a (blank) and I want to do (blank)” The product can change if the user stories (customer requirements) change Docs should be based on user stories as well As I said, this sounds foreign if you’re used to long doc-development cycles… … and doc plans that are cast in bronze at the beginning But the concept of user stories is actually very good news for us Because they mean that everyone is doing audience analysis – which we’ve been doing for years I’ve already spoken of the need to be flexible, because changes will come To accommodate change, the product developers break up their plan Into a series of short stages called iterations or sprints At the end of each sprint: They have enough pieces of the product that they could ship it, if needed They look at the landscape and see what features to develop next – based on customer requirements The doc team needs to be able to do the same thing: Be prepared to ship the doc that you have (by assembling the topics together) Be ready to change plans based on the current landscape
• #20: The doc plan, my “guiding light”…. What happens to it? It doesn’t go away But not it’s subordinate to the content strategy
• #21: The content strategy ties together the “big picture” What’s the total package of content that I have, including Traditional docs User-generated content Marketing content Etc. How can that package be deployed to meet the goals of the business? It covers the whole content lifecycle (per Rahel Bailie): Starting with analyzing the data you have (this is essential) Collecting the data you need Managing it Publishing it – and eventually sunsetting it … .And then the cycle starts again It’s a strategy – a “big picture” document and not a set of tactics
• #22: As the PM, you might also perform the content strategist role More likely (and ideally) this is somebody else But you need to know what they’re doing – remember: the content strategy will inform your doc plan in a major way We (tech writers) used to be gatekeepers : Decided what information people would see, and how they see it Now we’re curators : Arranging the information for the best user experience (like a museum curator arranges exhibits) Twitter Times is already using the “curated by” phraseology! Big picture: What are the company’s overall goals? Marketing messages? The organization develops a strategy – not just a set a tactics – and then implements the strategy This is now the context for your doc plan These are the activities you’re planning, managing, and tracking
• #23: You saw this slide earlier: It’s a summary of what the PM does Expectations: Now we deal with questions like Where will content come from? Who’ll use it? In what formats? Assign people and schedule work Who’ll do what? When? Some of the work is stuff we never did before, for example creating metadata or managing the Content Management System Control the process: It might be a challenge to find the right metrics for stuff like UGC All the more important to agree with management about what to measure (this is an expectation too) Respond to change – always important, but now even more so Analyze and report the results – same as always
• #25: Reviews: Reviews are probably ad hoc when dealing with UGC, or on a small Agile scrum team Also limited in scope – a few topics rather than a whole book Legacy info: We get so focused on NEW content that we can forget that the OLD content is still there Is there stuff from release 1 that’s no longer true for release 2? Editing UGC: Need some editorial/style control – but don’t want to “nannyize” the community to death Agile: Editing has to be shorter, more focused (like reviews) – how do you keep the big picture in mind? How do you fit editing in when there’s pressure to ship on short notice (do you ship, and then edit later?) Translation: Similar to editing If the schedule is short sprints; if there are small pieces of content rather than large groupings of content… ….How in the world do you plan for it, schedule it, and estimate it?
• #26: Tech Pubs has always wanted to be a full member of the team It’s even more important now With UGC and Agile, the landscape is ever more changing… … And the latest status of the project often isn’t communicated through formal channels (like design docs) So it’s even more vital for Tech Pubs to be “in the know” If necessary, find a champion Someone who understands the importance and value of Tech Pubs – perhaps the overall PM Being “in the know,” and having a champion… … .It’s more likely that doc drafts will reflect the current reality of the project Hence they’re easier to review You can also make reviews more focused, or targeted Review only a few topics, directly pertinent to what the SMEs are working on right now Each SME will feel invested in doing the review: Because they know that they’re one of only a handful (reviews are targeted, focused And because, by narrowing the review to topics they’re most interested in, you respected their time Warning: Someone needs to step back and see the whole forest, not just the trees Arrange a “big picture” review with one or more trusted SMEs Good news: You can hold that review whenever it fits into the schedule: it’s not sprint-dependent Tracking of the reviews is more important They’re smaller and shorter, but there are more of them As the PM you want to be sure that everything is being reviewed…. Properly On schedule By the right people
• #27: Remember the first step in creating a content strategy: Take an inventory of the content you have It’ll tell you: What you no longer need What will (or might) need to be updated What you can keep as-is If you skip this step (the content inventory) you’ll just have a vague sense that there’s un-looked at content sitting out there But when you do the inventory: When you’ve identified what will (or might) need to be updated, then you can arrange to have it reviewed When you’ve identified what you no longer need, then you can get rid of it…. … .And it won’t mess things up This content is best reviewed by an experienced SME Granted, they’re hard to find But here’s some good news: The timing of the review isn’t dependent on the iteration schedule The review can be done at any time, perhaps a few days between iterations The SME might be more amenable to conducting such a review if the PM lays out some ground rules The SME knows that he or she is the only person doing the review. He or she has more invested in the project He or she also knows that other reviewers won’t question or try to “fine tune” the things they recommend Delineate exactly what material the SME should review, and what material can be left out.
• #28: Rather than scheduling editing as a one-time event, make it an ongoing process Have the editor edit topics rather than the whole document Disadvantage: The editor doesn’t get the “big picture” view that a whole document affords But that’s OK: in topic-based authoring we sometimes don’t know all the uses to which a given topic will be applied Ideally (in any kind of process) the editor is part of the team throughout Not taking part in scrum meetings, but tied in closely with the PM and the content strategist Content strategist advises the editor of the content strategy (duh): What the overall objectives are How the information (most likely) will be used downstream What editorial standards exist – terminology and style Style guides have always been important…. … But now they take on added significance They help ensure that all writers follow the same rules as they write their various pieces of the documentation package Still to be solved: The benefits of the old “comprehensive” edit Agile’s “good enough to ship” mentality vs. the editor’s “let’s get everything right”
• #29: How do you fit a localization schedule into the sprints? How do you localize UGC? Richard Hamilton: break the translation job into small pieces Good practice: Translate the docs for each iteration separately Hamilton says breaking up the job is ALWAYS a good idea, in every situation One benefit: Doing it the old way, I interacted with the Translators maybe once every 6 or 9 months They didn’t know me well, and I didn’t know them Often I’d start the process only to find that a tool or procedure had to be updated I had to re-learn the process Dealing with the Translators on a per-iteration basis Keeps the relationship going Ensures that I haven’t gotten out of date w.r.t. tools & processes This also allows me to follow Anne Gentle’s advice: Always have doc that’s customer-ready If you translate in small chunks as you go along, you’ll have doc that’s customer-ready By the way, the software developers are facing the same challenge They’ve probably found ways to translate the User Interface, within the Agile framework Piggyback off their process
• #30: In many ways we (the Tech Pub community) are going into uncharted territory I hope to have an ongoing dialog about best practices How can we share our discoveries? Web 2.0 should help us…. Agile Tech Writers on LinkedIn An STC blog or forum? Besides Web 2.0 and Agile, what other new trends are coming that will affect our profession?