Chapter 2: Agile¶
Community discussion¶
In relation to Agile work environments, technical writing seems to fall into two general categories: technical writing developed either in an Agile workflow or alongside an Agile workflow.
Regardless of which category you’re in, many of the comments from our community point to the significance of proactive documentation development. The documentation isn’t going to write itself and that means technical writers can/should:
- Develop relationships with SMEs .
- Keep pace: Know what features do and when they will be released (and know who to ask about these things).
- Take part in sprint plannings, retrospectives, product demos, and so on.
- Make documentation part of the product.
- Bring visibility to yourself, your role, and the value of your work.
Being Agile¶
You may not use Agile to develop documentation but it’s useful to be familiar with the development methodology your engineering teams use, even if you aren’t necessarily part of their sprints/dev cycles.
Having PMs include documentation in their definition of “done” can be helpful.
- Improves accountability, visibility, inter-team/role communication.
- Can help to ensure your documentation gets reviewed (in a timely manner).
Software development is sometimes very fast-paced (agile - har har) - documentation needs to keep pace.
Tip: Get email notifications for pull requests to master - i.e. this is going into the product and I need to check what, if anything, needs to be documented.
Proactive Self-Starters: Participation and Visibility¶
Attend scrums, sprint plannings, retrospectives, product demos to keep up with new features. This helps others not forget you. This is important if documentation isn’t at the center of development, which it usually isn’t.
Face-to-face interactions are very helpful for documentation:
- Easier to ask questions, bounce ideas off of people, have meaningful dialogue as opposed to the Q&A a Slack exchange or email chain might become.
- Improves visibility by showing your involvement.
- May be a chance to provide product feedback - Tip: If something is difficult to document, this may be an indicator that it’s poorly designed.
Develop relationships with your SMEs.
Do not shy from approaching people with questions.
Having your SMEs ELI5 (explain like I’m 5) is helpful for getting to the heart of what a feature does.
Product requirements do not always equate to what the product does - find those that can explain functionality.
Know your customers (or someone that does). Have visibility on issues they experience and common questions. This indicates places to improve documentation.
Make the documentation and its changes trackable. This maintains organization for yourself, your team, those relying on documentation, and provides a record of what changed when.
Aside: Sight Procedural Issue¶
If you work across numerous teams, you may have a chance to see misalignments which affect the overall process and, in turn, the end product.
