How to Incorporate Product Documentation - Any Literature?
I'm a tech writer. I've worked in Scrum environments for 20 years now. Not once (literally) has there been a remote possibility to grant a tech writer 100% membership on a team. I have been the sole support for as many as 9 teams concurrently, and now am in a team of 3 writers supporting 11 development teams. Ratios of 1:15 or more are just a reality these days, so there's no way a writer can be assigned 100% to a team. Also, no team needs a devoted writer for every sprint.
Yes, I have read the manifesto (Working software over comprehensive documentation). Whether the manifesto can admit it or not, to sell certain types of software you must provide comprehensive documentation -- the customer demands it (sometimes as a point of legality). Let me put it this way... Would YOU pay a million dollars for software that doesn't have documentation? Only a commodity (a toaster) doesn't need documentation (actually, by law a toaster DOES need documentation). An undocumented marvel is great, but risks being a loose canon likely to burn money, or worse (like... kill people?) I hope this forum is not devoted to makers of commodities and loose canons. </soapbox>
Our current improvisation makes the pubs team external to the scrum flow. We write concurrently. Some of our source is docs-as-code, so it must meet code freeze. That is tracked as definition of done for a story. Other content can be deferred -- we release a week after freeze, so we have an extra week to cover so-called "external" docs. Tracking is not easy, and we constantly fiddle with our ticket system to refine dashboards that keep us up to date with the teams. There's no way we can attend every planning or grooming session. Note that meeting code freeze means we don't see the sprint demo until the day before deadline... Most writers like more than 24 hours to write up a feature. Many of them like to sleep. We are tremendously lucky that we were included in the transition planning... That is a FIRST for me as a tech writer. It might have given us an approach that can work. So far things are better than any other Agile/Scrum environment I've worked in.
The point is, we just made things up as we went along. Is there no literature that addresses the realities of customer satisfaction and documentation requirements in the Agile/Scrum world? It would be comforting to learn from the experience of others. Any input is welcome... Thanks.
Ratios of 1:15 or more are just a reality these days, so there's no way a writer can be assigned 100% to a team.
Scrum doesn't say anything about having to be full-time on a team. For the time that you are there however -- collaborating with other team members to craft a Done increment -- you would be expected to be 100% committed.
In your situation, is there a problem with commitment that impedes technical writers and stops them from being Scrum Team members?
Thanks Ian... I guess I have to ask what you mean by commitment. Of course we're 100% committed to the success of our project. If I pick up any work, I'm fully committed to that (other crises notwithstanding).
If I take tasks from teams A, B, C, and D... To be committed do I have to attend all the meetings for those teams? That, for example, would be a problem. Meetings overlap, and there's a threshold where meetings take over your day. Also, there's an impact that comes from context switching. Imagine trying to resolve 4 bugs at the same time, all in different parts of the code base, all for teams with different leadership... But you have to deliver the fixes at the same milestone.
So maybe it would be interesting to explore what you mean by commitment...
As per the scrum guide:
The Scrum Team commits to achieving its goals and to supporting each other.
Developers are the people in the Scrum Team that are committed to creating any aspect of a usable Increment each Sprint.
Although the Sprint Goal is a commitment by the Developers, it provides flexibility in terms of the exact work needed to achieve it.
We use the word “developers” in Scrum not to exclude, but to simplify. If you get value from Scrum, consider yourself included.
If I take tasks from teams A, B, C, and D... To be committed do I have to attend all the meetings for those teams? That, for example, would be a problem. Meetings overlap, and there's a threshold where meetings take over your day. Also, there's an impact that comes from context switching.
In my opinion you are trying to commit to too many things at once. There is a Kanban concept of limiting the work in progress(WIP). If you are having difficulties delivering to 4 teams try limiting that to 2 teams at a time, or even better 1. Yes, it may take you longer but it will also allow you to be more careful resulting in better output. If the company you work for truly values providing quality to the customer base, then they will need to adapt. It could mean lengthening delivery cycle or providing additional people to get the work done in the time that is being demanded.
Unfortunately too many people think that agile means you can move fast. In reality it means that you can adapt to changes quickly. There is no guarantee that you will do things faster but you will be able to adapt to changes that occur so that you waste less effort on something that could end up being unneeded. I have dealt with your situation in my career and sometimes I have been successful in helping others understand. But I have also not been able to impart that wisdom and left the company because of it.
A point I'd like to make about the Manifesto for Agile Software Development. The 4 statements on the front page are not strict policies. They are values. The ones on the left are valued more in order to help a team adapt to changes but nowhere does it say that the ones on the left are not needed or valuable. I agree with you that some documentation is required or extremely useful to have. Many things can be forgotten if it is only communicated verbally. And memory of events often change over time.
You mentioned in your original post that you are already external to the scrum flow. There is nothing wrong with that and in fact, might be the best place for you to operate. But as such, you shouldn't be subject to the same boundaries as the people operating in the Scrum framework. I also don't see why it is your responsibility to discover what needs to be documented. It should become part of the Scrum team's Definition of Done to provide you with what you need in order to be writing effective and valuable documentation. After all, the Scrum Team is responsible for producing work that is valuable to the stakeholders. If they are not providing the information to you, they are not fulfilling that responsibility. You become a stakeholder in the work that they do in order for you to do your job. Just as your Support organization and your Sales organizations are stakeholders in the work being done. Stakeholders are not limited to the people that use the product.
Thanks @Daniel Wilhite... A few points:
"If you are having difficulties delivering to 4 teams try limiting that to 2 teams at a time, or even better 1."
Effectively, what you are saying is that I should change the writer/engineer ratio from 1:15... to 1:7 or better. The realities of the industry don't usually make that possible. Either that, or I should double the time to release... Again, that decision is far above my pay grade. This is why I'm asking about literature that "realistically" incorporates product docs in Agile/Scrum. The theory of Agile gives obvious answers to my dilemma. But in practice, these obvious answers tend to be used as a means to brush aside concerns from the doc team, and leave them without recourse (my anecdotal experience).
At my company we've come up with something, it seems sustainable, and we have a sort of hybridized inclusion in some of the rituals. We have tweaked our ticketing system, taking liberties with some fields, adding other fields of our own, and building custom dashboards that give us varying degrees of success. We still need to tweak things at a fundamental level, more than 5 sprints in. Yes, I know constant revision is a principle. But imagine switching from LESS to to some other framework every sprint. That's more like the level of adjustment we are still making. It is getting better, but there's lots of trial and error. A framework that minimizes our trial and error would be nice.
In my company we were fortunate that the people implementing the transition to LESS were committed to making things work with doc. As procedures gelled, we had a voice in how our contribution figured. But these were approximations at best, and we're still thrashing a bit.
Finally, you say:
"[Given that you're external] you shouldn't be subject to the same boundaries as the people operating in the Scrum framework. I also don't see why it is your responsibility to discover what needs to be documented."
As a team we function externally. But there's a category of our source that has to merge in the same delivery schedule as the code. Docs-as-code is an increasingly popular and effective approach. Also writers need to SEE product to effectively document it. Also, writers should be included early -- this is a well-known principle. So whether we SHOULD be subject to the same boundaries, we risk exclusion and we have to meet the same deadlines.
In our environment we can check out a feature branch and build the GUI locally. This is great -- We can see the feature early. But we still get surprised by changes that impact docs, yet don't surface. It's everybody's responsibility to discover what needs to be documented. We know more intimately what those needs are, relative to the system (yes, system) that comprises our doc coverage. It's not realistic to rely on all stake holders EXCEPT docs to determine what needs to be documented. (At best, that reliance would be demeaning.)
I guess my bottom-line point is, there are nuances. I appreciate that the literature covers nuances of product definition, prioritization, dev, test, and delivery. I'm wishing for coverage of the nuances for documenting a product in this context. If it's not there, maybe there's room for a Pubs manifesto! :)
Bumping this one last time... I'll assume there is no formal literature that addresses specific, real-world product documentation concerns. And I'll point out that this is not an unusual issue... I would be surprised to find many (if any) technical writers who experience the A-HA level of comfort and benefit that an agile project is supposed to deliver.
So... Winging it as usual!