This month’s Tips & Tricks columns look at the world of documenting the user interface (UI). Today’s article provides some general thoughts on keeping up in this always changing area. We will also be looking at tips for technical writers working in smaller and in larger teams later this week.
A large percentage of technical communicators work with documenting software applications, and that usually means describing how a user interface works. An equally large percentage of tech writers have experienced projects in which that UI changes frequently, substantially and without warning… Sound familiar? Whether you’re a lone writer wearing multiple hats, or part of writing team in a large project, there are things you can do to stay on top of the changes and provide usable and relevant support to your end users.
Stay in the loop from the start. Make friends withthe lead developer, lead tester, and project manager or coordinator. Get on the communications stream for project updates and development status. Sit in on regular meetings (huddles, scrums, whatever the term is for your development environment). Take notes on major hurdles, issues, problems solved. Map them to the business and functional requirements, and ask questions when you see gaps. Do not rely solely on email for rapid responses to your questions.- Be proactive about access. Get access to development/testing environments and the defect tracking system. Make note of high priority bugs and anticipated delivery/retest dates. Enter defects you find as you work with the test system, and monitor changes to defect status.
- Create a documentation plan. Seems like a no-brainer, but it’s often set aside when you go into firefighting mode immediately. Lay out your documentation approach and structure early. Resist function-by-function documentation, and work towards concept/procedure/reference approach that centers on the user. This will help prioritize updates to key functionality that is most relevant to your user base.
- Know your development team culture. Once you understand the methodology the developers are following, trying to follow, or floundering with, you can better assess the overall challenges you’ll face in documenting the user interface.
- Assist with SLDC documents. Offer to support the project manager/coordinator by assisting in organizing/developing project docs (especially scope, business requirements, and functional requirements). If they’ve been written, track them down and review them thoroughly. They will help inform testing, user documentation and training deliverables.
- Use a source control system for your docs, images, style sheets, and scripts. If you have to roll back to a previous version, it’s a whole lot easier. Use a consistent naming convention for screen shots, etc., recapture with the same name.
- Review development status regularly. Schedule regular meetings with fellow writers (if you have them), and with your QA and development contacts to address impacts from bugs, change requests, and testing issues that will affect multiple parts of the system.
- Monitor documentation status continuously. Set aside a time each day to review defects, project status, issues, etc., against your schedule and your deliverables. It will help uncover the things most likely to change. Don’t work on them now if you know they’re being fixed next week.
- Set a date for documentation freeze. The development team should have an official code freeze for the user interface, and so should the user documentation. Schedule the doc freeze with enough time for you to review all of the documentation, and make sure it’s communicated.
- Use your tools to their fullest potential. Take advantage of the advanced features or workflow functionality in your help authoring and structured documentation tools to identify and closely manage those pieces that are most likely to change before release. Integrate project and development docs in your system to reuse and link to content that informs the UI.
A special thank you to Adobe Systems, Inc. for sponsoring our Tips & Tricks column. You can learn more about Adobe’s industry-leading technical communication tools by going to their website.
Did we miss any? Let’s discuss in the comments …
