by Frances Advincula

The  last few days was my first foray into the agile practice of the planning game, wherein stakeholders, programmers, and the rest of the team go in a room and brainstorm, think, talk, and fight in order to come up with what we are actually going to build. It was really mind opening to just see how the dynamics work — the software architects and programmers tend to really have lots to say, because, well they’re the ones going to build the software. On the other hand, it was also interesting to see how the QA and the documentation team asked a lot of questions, and usually ones that customers will most likely be asking. It really reinforced me once again how great debate and teamwork ultimately leads to a better product.

On the Value of Documentation

Let’s start with appreciating the work of the technical writer on your team.  I think it would help us, as developers, to know where they are coming from, so that we can work more productively with them. 

I know sometimes developers tend to brush off doc as “just doc”. What do you have to say about that?

We hear the myth time and again, “no one cares about documentation.” I brush these comments off because as I see it, no one knows they care about documentation.  I believe this stigma comes from the amount of bad documentation people have been exposed to in the past. They didn’t have good technical communicators writing quality documentation.  And there are still writers out there perpetuating this myth through bad documentation. However, there is a new generation of technical communicators out there who I like to call Docvocates. They are the ones who are actively working on eliminating this myth by producing quality work and speaking out about what we really do. I hope we can change the way people view doc, but it may take a while. These are what I view as the top three benefits of good documentation: 

• Eases cognitive friction
• Improves the chances of product success
• Reduces the number of support tickets 

The proof is in the metrics. The thousands of visits we get to our documentation site, the emails we receive from customers asking for more information on a product or process, and the research completed in the field all point to the value of documentation. A lesson I’ve learned in my field (which could apply to many others) is this: Know your value, even when others do not. People read documentation; they just don’t like to admit it.

Is there anything you wish developers knew about documentation?

Technical writers don’t want to be developers. I make this statement because if you look at the history of technical communication, the initial writers were developers and engineers. It wasn’t something that people went to school for, and it wasn’t necessarily something many developers and engineers wanted to do. Sure, that is still the case in some companies that are behind the times, but for the most part, technical communication is recognized as its own profession and academic program. The field has made tremendous strides over the last decade and will continue to do so in the coming years. And it’s not just about writing. For a lot of technical communicators, writing is only 10% of what they do. They are information architects, document and web designers, content strategists, and usability specialists.  Technical writers need developers for their subject-matter expertise, and developers need technical writers to bridge the gap with their users. While they don’t want to be developers, there is a relationship there that will always remain and should be fostered.

If developers could do just one thing to improve the process/help you perform your job better, what would it be?

Give technical writers time. Whether they need more information about issues to write release notes, or information about functionality to write the doc, take some time to answer questions. Doc teams obtain the technical information from developers and turn it into something understandable for the user. The longer developers take to respond, the shorter the time writers have to do their jobs. That timeline impacts the quality of the work, and it impacts how users view the product.

In your opinion, do you think doc has a place in startups?

Yes. Sam Carpenter will do a much better job of telling you why: Why Startups Need Documentation.

On the Value of Project Management

I also just started my masters at Johns Hopkins, and I’m taking a class in project management. Let me tell you — I have never appreciated my managers more! Between responding to request for proposals, creating work breakdown structures, really, my head just spun! With that in mind, let’s see how we can cooperate better with our managers (I noticed we developers sometimes can be quite anti-management.), which will ultimately help make the team more successful. 

Is there anything you wish developers knew about your job?

I do wish that developers understood the importance of project tasks that don’t include coding.  Most developers are good with this, but some don’t understand the importance of things other than coding.  I know things like time tracking are not that exciting, but accurate time tracking is extremely important as far a project reporting goes. Which eventually rolls all the way up to asking for more funding next year to increase the team size (or to keep it the same) so that we can continue to deliver great code.  It’s not enough to deliver great code. It must be on time and on budget as well.

If developers could do just one thing to improve the process/help you perform your job better, what would it be?

Communication, some developers get offended when you ask them what they are working on or when they will be done. Estimates are hard to give, and I understand that, but we also have to give them. We can handle it when we are wrong with things such as change control but often developers hate to be tied to do a time estimate. 

Is there anything you wish they would stop doing? 

For the most part I have always worked with great developers. One thing that is hard for them to do is to deliver code that is good enough.  We should always strive for great code, but you can spend too much time tweaking code. With us trying to hit market demand we must be agile and fast. In no way should we ship bad code. Sometimes though we need to ship good code… not excellent code. This is a very hard line to decide what is good enough.  It’s very hard to tell developers that as well.

Also, I know that QA and documentation are not developers’ favorite thing to do, but they are necessary evils and it makes my job easier when developers just do what they need to do instead of belly ache about it.

I hope you have learned something from these interviews as I have. I know I am very guilty about some of these sins! I especially hate giving estimates, but like the interviews said, we must all do our part to ensure that the team succeeds as a whole.

One more thing, although I am very disappointed that Femgineer wasn’t mentioned, here is a goodie-bag for your women-in-tech resources fix. Happy weekend, Everyone!

Frances Advincula writes the series Frances Fridays. Frances recently graduated with a degree in Computer Science with specialization in Software Engineering. She now works as a Software Developer for Accenture (Software). A proud geek girl, she’s sure she is the only one who can’t play video games. Follow her random musings at @FranAdvincula.

Tweet This Post