I don't think I've ever been involved in an Agile process that included Doc in the core team, but now that you raise the point, that's clearly a process failure.
After my first (full, not intern) position where I was included as part of the core team, I've made it a hard requirement. Fortunately, since then, I've been able to insist -- meaning that (a) so far I can afford to be picky and (b) I have a very solid track record that means I don't get dismissed out of hand. People just starting out won't necessarily have those traits, but I always advise people to, at the very least, prefer companies where they'll be part of the core team if they're comparing offers.
The cost, to the doc person, of being included early is that you might have to redo some work and/or relearn some things, because until the feature is finished it can still change even though everybody agreed on a design. That happens -- QA discovers a performance problem that can be alleviated if you make this small change to the interface contract, or it turns out that this is inconsistent in some way that matters with that feature over there that's also going into this release, or whatever. (But I don't need to lecture you about this; you know how software-dev works.) So that's the cost, but against that there are huge benefits for the team. You alluded to UX benefits; specifically, doc people are already looking at things from the user perspective so they'll spot things or have suggestions that people deep in the implementation might not think of. In most organization, in my experience, there are a lot fewer writers than developers and a writer might be working with more than one dev team -- and therefore might know some of what's going on in that team over there that affects this one here. And a really big one IMO: trying to explain something is a really good way to find problems in it. You know this from rubber-ducking. So even if some work might have to be revised, I want a writer to be trying to explain the new thing early, early enough to make changes when those problems emerge. (A writer, in turn, learns to use a breadth-first approach and focus on key areas for early deep dives. If you're working like this you don't start at the beginning of the doc and work your way through it in order.)
Of course, I've too-rarely worked anywhere that had genuine professionals doing the documentation to begin with, which says something in and of itself.
That's true lots of places, yeah. And, to be fair, there are more than a few technical writers out there who don't know how to work in this kind of environment, who struggle with changing requirements, or who just want to start with a finished thing so they can take an orderly approach to the doc instead of helping to make the thing. It'd drive me nuts, but not everybody is like me. There's also a lot of poor "walk the menus" (or equivalent) documentation out there that makes people think that's all technical writers can do, and that doesn't help. I've had several senior developers and dev managers say to me, after some time working together, variations on "I had no idea that tech writers could do what you do" -- they'd never seen it before. I'm not saying this to brag; this is as much about mindset as it is about raw skills, after all. But it's something I've tried to imbue in every junior writer I've mentored over the years.
Yet another reason why I desperately want to have enough money to staff Querki properly...
There are so many needs and only so much money. It's a hard juggling act. What we're talking about for doc you also need with QA. Plus, you know, the developers who are going to build the thing, and all the outward-facing work (getting your product to be used), and some level of admin support... building a company sounds really complicated.
no subject
After my first (full, not intern) position where I was included as part of the core team, I've made it a hard requirement. Fortunately, since then, I've been able to insist -- meaning that (a) so far I can afford to be picky and (b) I have a very solid track record that means I don't get dismissed out of hand. People just starting out won't necessarily have those traits, but I always advise people to, at the very least, prefer companies where they'll be part of the core team if they're comparing offers.
The cost, to the doc person, of being included early is that you might have to redo some work and/or relearn some things, because until the feature is finished it can still change even though everybody agreed on a design. That happens -- QA discovers a performance problem that can be alleviated if you make this small change to the interface contract, or it turns out that this is inconsistent in some way that matters with that feature over there that's also going into this release, or whatever. (But I don't need to lecture you about this; you know how software-dev works.) So that's the cost, but against that there are huge benefits for the team. You alluded to UX benefits; specifically, doc people are already looking at things from the user perspective so they'll spot things or have suggestions that people deep in the implementation might not think of. In most organization, in my experience, there are a lot fewer writers than developers and a writer might be working with more than one dev team -- and therefore might know some of what's going on in that team over there that affects this one here. And a really big one IMO: trying to explain something is a really good way to find problems in it. You know this from rubber-ducking. So even if some work might have to be revised, I want a writer to be trying to explain the new thing early, early enough to make changes when those problems emerge. (A writer, in turn, learns to use a breadth-first approach and focus on key areas for early deep dives. If you're working like this you don't start at the beginning of the doc and work your way through it in order.)
Of course, I've too-rarely worked anywhere that had genuine professionals doing the documentation to begin with, which says something in and of itself.
That's true lots of places, yeah. And, to be fair, there are more than a few technical writers out there who don't know how to work in this kind of environment, who struggle with changing requirements, or who just want to start with a finished thing so they can take an orderly approach to the doc instead of helping to make the thing. It'd drive me nuts, but not everybody is like me. There's also a lot of poor "walk the menus" (or equivalent) documentation out there that makes people think that's all technical writers can do, and that doesn't help. I've had several senior developers and dev managers say to me, after some time working together, variations on "I had no idea that tech writers could do what you do" -- they'd never seen it before. I'm not saying this to brag; this is as much about mindset as it is about raw skills, after all. But it's something I've tried to imbue in every junior writer I've mentored over the years.
Yet another reason why I desperately want to have enough money to staff Querki properly...
There are so many needs and only so much money. It's a hard juggling act. What we're talking about for doc you also need with QA. Plus, you know, the developers who are going to build the thing, and all the outward-facing work (getting your product to be used), and some level of admin support... building a company sounds really complicated.