Working on a large development team with multiple writers, provides some clear advantages over the lone writer. At the same time, a large team presents some unique challenges. Here are seven tips for managing the tech comm effort when the User Interface (UI) is a constantly moving target.
A good UI shouldn’t NEED documentation.Figure out how much input you can provide during the design phase, how much documentation you can eliminate by providing embedded help.Field-level documentation/embedded help should be something the user can turn on/off. It’s an improvement over online help since it’s inside the product. But delivering embedded help means you have to meet engineering deadlines rather than documentation deadlines and you have to commit the descriptions to their code, which is a challenge if your team isn’t used to engineering version control software like CVS.- If you must document the UI, document user goals not functionality. The documentation shouldn’t detail every field or option because no one is ever going to read it (except for QA). Even if they do, it won’t be useful because it will lack context. For example, with an on/off switch, the most you can document is that if you switch it off, “functionality A” will be off. Useless. There’s no context connected to their larger goals. This is your chance to be a user advocate instead.
- Be smart and SINGLE SOURCE. When working on a team where user interface documentation could show up in any number of deliverables, it pays to single source your development. In DITA environments, you can write UI file paths once in one topic, and ‘conref’ them in as needed. So, when they change the UI you can just update content once and re-publish correct documentation product-wide. You can also use this approach with FrameMaker text insets.
- Base your documentation on a working UI. Don’t be afraid to put documentation on critical path. Documenting anything else, like “future functionality” based on requirements docs, is simply a set of guesses and won’t hold up when a build hits the test environment.
- Cozy up to the lead QA and lead Dev people to keep on top of their schedules and get the alerts about things coming down the pipeline. Communicate those alerts to everyone on your team.
- Plan for additional complexity in goal-focused documentation. If your team documents each piece of functionality/widget as standalone topics, then addition or removal of functionality/widgets is not too hard. But if you’ve taken your documentation to the next level by writing user goal-based documentation (which essentially documents a set processes and functionality to follow to get to the likely goal the user, has—e.g., create this item, turn on this functionality, set these three things like this, and voila, you’ll have fresh bread out of the oven in time for dinner or a VM that always has the OS you want and is always up when you need it), adding or removing widgets has a much larger impact on the documentation timeline, because you have to identify how that functionality fit or will fit in to bigger user goals and modify the affected sets.
- Provide convenient help to end users. Remember, users will go to the documentation if the information they want is not in the user interface itself, like specific restrictions. Put this information in a quick lookup table (reference topic for DITA authors), not embedded in tasks.
A special thank you to Adobe Systems, Inc. for sponsoring our Tech Writer Tips & Tricks column. You can learn more about Adobe’s industry-leading technical communication tools by going to their website.
Do you have other tips to add? Let’s discuss in the comments …
