No no no! I’m not reopening the discussion on that myth that there’s no documentation in agile. I’m sharing feedback from one of the technical writers I had the pleasure of working with for many long months (Christopher Nelmes to name him). As we were going to spread the good word to other technical writers (how do you translate that? -ironic- the people who do the documentation, you know), I asked him two years ago for some feedback on his impressions and how to approach agility when you are solely (and that’s a lot) responsible for documentation (end user).

I’m not saying I agree with everything, but his point of view is interesting. We’re in Scrum, it was decided that he would be integrated into all the department’s teams (let’s say three to five). Beyond two or three the workload proves untenable, and quality degrades (as always), and so he had prioritized his involvement (by value) on two or three “flagship” teams/projects.

I really like this alternative perspective and as you read it you’ll immediately understand the full benefit of varied profiles within an agile team. The combination of profiles and its expected benefit: collective intelligence. (This text is therefore two years old).

Here’s what he wrote to me (I’m translating, the original version is below).

Getting started with agility as a person responsible for user documentation

and integrated into several teams.

How to update existing user documentation during agile developments

• Attend all sprint planning meetings
• Get familiar with the teams and identify principal contacts (scrum master, product owner, etc)
• Identify (quickly) the impacts of scrum projects in the different pre-existing documentation - always think to ask if there will be more impact, particularly in areas that are less clear, obvious, initially.
• Don’t take for granted if you are told that there will be no impact. Find out for yourself what the changes are. The person in charge of documentation knows their domain and will understand certain impacts that will remain invisible to a person less familiar.
• Create chapter titles, themes. Make your chapters easily identifiable and so they can be associated with user stories and sprints.
• Try to flesh them out enough so they provide a global and coherent understanding of the scrum project.

How to create user documentation during agile developments

• Review all the points seen above.
• Initialize a complete table of contents for the documentation. The documentation manager (Technical Writer) must know the entire scope of the new project, even if they don’t know the details, nor the precise content, they must be able to know the complete path.
• Identify the parts particularly impacting user documentation even without knowing the project/product details.
• Create chapter titles, themes. Make your chapters easily identifiable and so they can be associated with user stories and sprints. Be careful there will potentially be many sprints/scrums in parallel.
• Try to flesh them out enough so they provide a global and coherent understanding of the scrum project.

Principal benefits of agile

• Active in the team from Day 1.
• Ease of access to information and people.
• Improved knowledge of workload and responsibilities by attending agile meetings and events.
• Clarifying point at the beginning and end of each iteration.

Principal downsides

• My teammates’ participation in reviews has been very inconsistent. I need thorough reviews. Sometimes my teammates’ involvement has been too light and has had repercussions later.
• The Product Owner is really important, they must really be good. I’ve known a PO who had simply forgotten to tell me something essential and I discovered it too late in the project.

• Lots of downsides if you’re not truly agile

  (knowledge, communication and existence of a vision for the

  project, lack of communication due to lack of organization (translator’s note

  non-compliance with the scrum framework)).

• A large part of the success or failure of documentation lies in interaction with key people (the product owner and sometimes the scrum master). Thus the relationship with these people is fundamental and will play a very important role in the quality and completeness of the documentation. Not much room for error (translator’s note : implied: if this relationship is bad, the documentation will be bad)

There you go, Christopher let me know if the translation doesn’t work.

Original English version

How to integrate Agile development into existing content

• Attend all sprint planning meetings
• Get familiar with the teams and identify principal contacts (scrum master, product owner, etc)
• Identify impact from a scrum in different guides – always think to ask if there is more impact, perhaps in areas that may not appear obvious
• Don’t take for granted if you are told that there is no doc impact. Find out for yourself what the changes are. The technical writer knows the content of the documentation and may know about a doc impact that someone else does not know about
• Create reqs. Make reqs easily identifiable and corresponding to scrum and sprint. There may be lots of concurrent scrums/sprints. Contain as much detail as possible to at least show the scope of the scrum project

How to integrate Agile development into new content

• All the above
• Create project plan for doc. Technical writer (TW) must know the complete scope of the new project even if the TW does not have any real details/content to be able to create a plan for the doc. Identify all areas of impact even without knowing all the exact details.
• Create reqs. Make reqs easily identifiable and corresponding to scrum and sprint. There may be lots of concurrent scrums/sprints. Contain as much detail as possible to at least show the scope of the scrum project

Principal benefits of Agile

• Active in the team process from Day 1
• Ease of access to information/resources
• Knowing about work loads, responsibilities, etc from meetings
• Summaries both before and after a sprint in planning and review meetings

Principal downsides

• I have experienced very differing levels of review comments. I require thorough review. Sometimes review has been done too quickly in my opinion and may have repercussions later.
• The Product Owner (PO) must really be thorough and on top of the game. I have had the experience of a PO simply forgetting to inform me of substantial material that required documentation at a late stage.
• All downsides apply to not using the agile principles (TW is not always aware of project – difficult to obtain information due to lack of organisation).
• Much of the responsibility for the documentation comes down to the interaction with few people (product owners and in one instance, the scrum master). Consequently, it is a relationship of great importance to ensure a high quality and complete documentation. Not much room for error.