Sunday, 4 April 2010
02:27 PM
Someone recently sent me a question that boiled down to "When you document a new product, where do you guys get your information?" When you're part of the documentation team that's working on a new, not-yet-released product, you can't just load up the product and start poking around, because for some significant portion of your scheduled time, there's no product to be poking around in. And by the time you get some early product builds that are stable enough to play around with, you're rushing toward deadline.
 So it's a fair question. I consulted with our folks, and this is the answer we came up with. First of all, the process varies a bit depending on the team, of course. Our general process is that product features are developed by feature crews that have team members from all affected disciplines (program management, development, test, and documentation, hopefully including localization). Feature crews develop an initial specification that goes through an approval/sign-off process. The product is then built from the spec, and we're done!
Haha. In reality, of course, things are often more fluid -- before, during, and after the development phase. Feature-crew specs are in general a starting point for our information, but like all specs, they vary in how much information we can glean from them, and as we all know all too well, the spec is often not maintained after coding begins in earnest. If that's the case, writers have to be a bit more resourceful in getting information. Sources of information for us therefore include:- Source code. In our group, the writers read product source code to discover how features work. This tends to be more useful when writing API docs, but it's a fruitful strategy generally. However, source code does not necessarily give you an overall picture, or user scenarios, or suggest a priority for which aspects of the product are the most useful to concentrate on.
- Talking with the relevant, um, stakeholders. It's hard to overemphasize what a boon it is to be on familiar terms with the program manager (PM) who owns a feature area, and the developers, and (sometimes overlooked) the test-team members. (Test is more-or-less by definition extremely aware about the state of a feature and testers are often excellent doc reviewers.)
- Early product builds. In general, we take "eat your own dogfood" pretty seriously. Most teams make available centrally managed servers that you can remote into in order to play with the current state of the product. As I say, for periods of time, especially early on, builds will be in a fragile state, so access to these interim builds is never guaranteed. But when you can get them, product builds are invaluable. Builds are where the rubber meets the road, so whatever it might say in the spec (or not say) about what the UI will look like, what error messages will say, etc., the product builds become the de facto spec.
- Collateral materials. PMs are often obliged to do demos, either internally (for higher management) or for conferences and the like. Their presentations and example code are often very valuable, especially for getting the big picture for features. (The big picture is often lacking in feature specs, because it's often assumed that anyone reading the spec internally already understands what problem the feature is trying to address. I blogged about this before.) You’d be amazed what you can learn about a feature from a good demo or from a PowerPoint presentation, including information you never find in a spec anywhere.
- Blog entries. Team members in the know – PM, Dev – often maintain blogs in which they describe bits and pieces of what they’re working on. These blog posts are extremely valuable, and more than once we’ve adapted a particularly key one into a doc topic. (Note that in some groups, simply pointing to the blog entry is considered good enough.) A couple of examples:
- Internal "bugs." I put the term "bug" here in quotation marks because this can cover not just real bugs (i.e., errors), but feature requests, design-change requests (DCRs), and so on. (The term bug, although ubiquitous, is actually not technically correct -- the formal term is work item.) Bugs (ok, I revert to old terminology) often either have implicit or explicit documentation impact, and we stand ready to respond to those.
After a product has been released (even in preview form), we can get additional information from a couple of other sources:- Bugs (again). People who use the docs, both internally and externally, can file bugs (exteral users can use Connect to do so). Most of the bugs we get are about details in a topic (code errors or typos), but occasionally the cumulative weight of bugs we get around some documentation will make it clear that we need to do some rewriting or reorganizing for a larger set of docs.
- Comments and ratings on topics. MSDN lets folks rate and comment on
MSDN wiki.
- Community content on MSDN. People can also add their own text to topics on MSDN, and these comments can be extremely useful information about what we need to add to the docs.[1]
- Forums. The ASP.NET forum and others (for example, we have an internal forums for ASP.NET questions) can be a good place for us to find ideas or information for docs or doc improvements.
The real answer to the original question is really more like "We get our information anyplace we can find it." I list all these sources as if they are laid in front of us for our convenience, but every situation is different, and it depends on the project, the schedule, the personnel, and other mutable factors. However, in every case it's some combination of these sources that helps us get the job done.
If you're a tech writer, help me out -- where do you get your information?
[categories]
writing
|
link
|