views:

329

answers:

13

At my company we are currently re-assessing which team will take on the responsibility of external documentation (end user, training and support documentation). We don't have a dedicated technical writer on staff and, like most development teams, our developers struggle with writing high quality, consistent end user docs.

Who should own this responsibility and why?

A: 

You need someone in authority to make sure it gets done (I guess managers should do that?). All 3 of these groups should have input. Product owners may be involved more during the requirements hunting and testing phases. Tech support may pick things up during testing and when they create training docs. The more imput they get from developers the better, but there needs to be some discretion to prevent taking up devs time.

Jeff O
+1  A: 

The documentation should begin with the developers, at least the technical documentation, and should be reviewed for quality control after the respective code passes code review. If the documentation fails quality control it should pass to an editor for clarity and uniformity.

+1  A: 

I would argue that without a technical writer, the ownership of documentation should fall on the developer, however, documentation should be the responsibility of the both the developer, support engineer, and marketing team.

The views offered by the developer/support/marketing people will be different by necessity, and each should have input in order for the documentation to fulfill it's goal.

Joel Spolsky has a good series on writing specifications that also touches on this.

chills42
A: 

IMHO a software developer should be able to write decent documentation. If he can't, then he's incompetent (that he's not the only one who can't write is a lame excuse). So cut his salary and hire a technical writer with the remainder - or if it feels better to think the other way round, double the salary of the other developer competent in writing.

While lots of people seem to be religious about strict role definitions and separating developers from writers, it doesn't change the fact that there are developers quite capable of writing good documentation, and they're obviously way more valuable than their tunnel visioned colleagues.

Joonas Pulakka
Developers are very bad at writing good end user documentation because they have no idea what questions a real end user might have. For them, everything is "obvious".
Aaron Digulla
Sadly, that's true for many developers out there.
Joonas Pulakka
IMHO a technical writer should be able to write decent software. If he can't, then cut his salary and hire a decent software developer. Honestly, I find the opinion silly. If you're paying someone to be a software developer (with a salary for that role), then you shouldn't expect them to be filling other roles. Should they be able to document their system/tool well enough for an actual writer to actually produce documentation? Sure... but you make is sound like "technical writing" isn't a distinct skillset.
RHSeeger
Role definitions are always arbitrary - note that I wrote "able to write *decent* documentation", not "able to write *top-notch* documentation". While "technical writing" is a distinct skillset when taken to high enough level of quality, the same could be said about "network administration" or even "talking". Would you hire a developer who doesn't know what an IP address is, or who is not able to form comprehensible sentences? I don't think so. A good developer is not a one-trick pony.
Joonas Pulakka
+1  A: 

Everyone should have a hand in writing 'documentation' in some way. For developers it can be as little as comments in the code to explain the intent of the code, to going as far as being involved writing design documentation and specifications. Tech support should be writing support documentation to support the application. Q/A should have documentation on how to test the product and a change log. Product owners should ideally if it is custom software have a copy of the specifications, as well as a 'user manual' if needed.

Not all of this 'documentation' will reside in the same place or even have the same purpose. In fact it is quite possible that you can have too much documentation for a project. It really comes down to common sense for what you need for your situation and project.

Scott Lance
+5  A: 

Technical writers own documentation. Developers provide technical insight, tech support provides troubleshooting insight and product owners provide the overall insight (uses, future directions, and so on.)

If you don't have technical writers, you should get the best writer in a team to be responsible for it. Roles are not important as long as all them are committed to providing the information the writer needs.

Vinko Vrsalovic
+11  A: 

Just my opinion, but... EVERYONE!

If documentation is not a collaborative effort, then something is bound to get left out. In terms of who drives this collaboration - well, I guess that's down to the individual circumstances of the project team; someone in a position of authority, that's for sure.

Chris R
+1 This is why I personally do all my documentation in wikis.
T.E.D.
I disagree. While there are programmers that write very well, there are very good programmers that write very badly. They would only produce documents that are unclear and hard to understand. Why waste their precious times if somebody else could document their work well?
Bruno Rothgiesser
@Bruno Hence the emphasis on collaboration. Programmers may not be great at writing well, but isn't it still their responsibility to convey the necessary information about the system to *someone* who is?
Chris R
I agree that everyone should have say and visibility, but if everyone is RESPONSIBLE then no one is.
cagreen
The problem I find with everyone simply having 'say' and 'visibility' is that people often don't exercise their right to contribute, as they do not see themselves as responsible for the delivery. You're right, there needs to be someone driving the process (in my organization that is typically the project manager) - but I still think that responsibility should be collective.
Chris R
"Responsibility should be collective" and "it won't get done" unfortunately sound equal to me.
Joonas Pulakka
+7  A: 

IMHO, having developers write end-user documentation is a very bad idea. Developers are good at writing code, not end-user documentation. If you've ever used software with docs written by the development team, you'll know what I mean. The docs are pretty much worthless for anyone that's not a developer.

Now if management is not willing to pay for a dedicated technical writer, I don't know what the best solution is.

JRL
While you're correct that developers usually aren't the best people for end-user documentation, they are the only ones with the full technical understanding of the system, and so it is necessary for their input to be a core part, without it, the end result is a series of useless screenshots by someone that doesn't understand the software.
chills42
@chills42: I totally agree with you. I'm just saying they should not be **writing** it.
JRL
A: 

My vote is with Chris Rice on this one ... everyone should own the documentation.

To this end, you should have all your docs in a wiki. That way anybody who is ever frustrated with innaccuracies or ommissions in the docs can fix it themselves, rather than just grouse about it.

T.E.D.
A: 

If you can, then set up a Wiki and a single person responsible for it. That means everyone can edit but that single person gets GOD MODE and can undo any change plus set the rules. This way, everyone can easily contribute to the docs and, if you choose your Wiki carefully, you can export it and ship it with the product or, even better, put it online for the end users to edit/comment.

Aaron Digulla
A: 

The answer depends on what kind of documentation we're talking about:

  • End-user documentation shouldn't be written by programmers, only exception is if they are really good at understanding a what kind of problems users need to solve with your application/program/system. You should really leave this task to a technical writer.

  • Code documentation should totally be written by programmers because they are themselves users of the code. If they're bad at writing, it's okay. Hopefully some other programmer in the team will correct logical errors, grammars or spelling mistakes that some are prone to do (but please write code comment documentation in seperate checkins/commits in order to avoid merge conflicts).

In the case of ownership I believe in collective code ownership among programmers. You can ensure higher quality if everyone has a helping hand in it. Except for end-user documentation unless they're really versed with all requirements that an end-user has (which is impossible in large scale scenarios).

Spoike
+1  A: 

A lot of these responses are talking about internal documentation. You didn't ask about that; you asked about end-user (external) documentation.

On any large enough project to have specialists, external documentation should not be written by developers. That's technical writing, and there are legions of folks out there working full time as technical writers. If you're a software developer able to write top-quality end user documentation, you're in the tiny minority of working developers today.

If you're a small team, too small to have a full time technical writer, you've got two choices:

  1. Find a part time technical writer.
  2. Have everyone own it, identify which subset of the group is best at editing it into a coherent whole, and make sure someone from that group gets the final copyedit.
Dean J
Thanks Dean. I am specifically looking for experiences with EXTERNAL docs (+1)
cagreen
+1  A: 

We have embarked on an interesting experiment to use a social media platform and a community approach to make our enterprise software documentation more up-to-date, accurate and relevant.

We definitely have found a divergence between writing styles of technical writers versus developers, QA folks, consultants etc.

We also are finding that varying incentive systems get in the way to creating the best possible documentation in an agile fashion. Developers mostly are incented to develop code in time and scope, technical writers to deliver style guide compliant documentation.

We do however see that the only effective way forward is a co-creation model, to lower the cost of understanding our products, and increase knowledge discovery effectiveness.

Andrea Anderson
This sounds very interesting. Could you elaborate on the implementation of this?
cagreen