AllenQuinn wrote:
Let's summarize for Stimulus.
Let's try not to be condescending.
IBM developers generally do not write their own Information Development Documents except for Readme and Release Notes. True.
It was said that the documentation would be very sad if the developer wrote the document. Ask any Websphere Customer, the documentation is in fact "very sad" because it is not accurate and is not comprehensive. The documentation is written by IDD people, or technical writers as stated, but the problem here again is that the technical writer does not have an uderstanding of how the individual components function and are designed to operate. So they do not have the developer's technical information .
I don't know what an Information Development Document is, but from what you've written, it sounds like your talking about documentation that is intended for technical users. It's documentation that is geared for a technical audience, most of whom are developers themselves. Is that correct?
If that's the type of document that you're talking about, then I agree that developers have to have a greater role in writing the docs.
That said, docs for developers isn't the only type of documentation that most companies and projects need. For instance, IBM has lots of support docs on its Web site.
This article describes how to troubleshoot common Bluetooth problems. You don't have to be the software or hardware engineer who developed something in order to write end-user docs like this. You may disagree, but IMO, these types of end user docs are better when they are written by technical writers than when they are written by developers. Developers tend to get too technical, use lots of jargon, and don't know much about audience analysis, information design, cognitive processing, and so on.
Also, you stated the technical writer would be in contact with the developer to get that information.
I said that tech writers at successful companies are in contact with developers and designers to get key information. The amount of information provided by a subject matter expert varies greatly, depending on the company and the project. The more technical the product and audience, the more information the developer has to provide. However, I wouldn't need anything from the developers to be able to create a fairly comprehensive "How to build a Web site in Joomla" tutorial that would show an end-user how to use Joomla to accomplish a wide variety of goals. While writing the tutorial, I could seek feedback from developers in order to cover more aspects of Joomla I overlooked, but it isn't necessary to creating a great resource for end-users. For instance, the author of "Windows XP for Dummies" likely didn't have any contact with anyone who actually wrote any of the core code of Windows XP.
Stupid, think about what you said. We all know you are going to correspond via a bbs, or email with a technical writer. So you are going to basically have to write the stuff anyway. See the point? NOPE!
I'm not a member of the core Joomla development team, so I don't write code for Joomla. Moreover, I'm not a programmer at all. I am a technical writer. I have my Bachelor's degree in technical writing, and I'm a self-employed tech writer, information architect, and usability consultant. I've studied enough computer science to equate to a computer science minor, but my programming skills are limited to HTML and CSS (and a little PHP and XML).
As a developer I write my own documentation, then have a writer, either technical, or not review what I have written to "unit test" the doc.
Back to Jakob Nielsen's article that I referenced earlier - your perspective is a combo of his stages 2 and 3 in the importance placed on maturity. In stage 2, the design team relies on its own intuition about what constitutes good usability:
Sooner or later, most companies realize the value of making designs easier for humans to use. At this point, the most obvious (but erroneous) approach is for the design team to rely on its own intuition about what constitutes good usability.
After all, the team members are human beings, and they use computers and websites. Surely they know whether something is easy to use or not. The existing team members also have one huge benefit: they're already onboard and participate in every project meeting, where they're not shy about sharing their design opinions.
This approach works reasonably well for one class of design problem: developing tools, such as Web servers, for developers or other geeks. Open-source projects like Perl, Linux, and Apache have had great success with developer-centered design. But even these projects could have been better with more systematic usability input from people outside the design team. Programmers who work on Apache's guts have a deeper understanding of it than other technical experts who only want to use Apache, not hack it.
For projects targeting non-geek audiences, it's disastrous to rely on the design team's understanding of what's easy. Anyone working on a project knows much too much about it to represent outside users.
Luckily, the difference between a team member's conceptual model and that of average users is easy to explain. It's also an easy pill for team members to swallow, because you're basically telling them that they're too smart and knowledgeable to stand in for the average user.
His comments focus on the interface of software programs and Web sites, but I think his points apply equally well to documentation. The next two stages of usability maturity reflect your practice of having a writer "unit test" your docs after you've written them. Nielsen writes that at this stage, usability is viewed
as a magic potion that's sprinkled sparsely over a user interface to shine it up. The main usability method is user testing, which is invariably conducted late in the development process after the user interface has been at least partially implemented.
When a user interface is teste dlate in the develop process - or a doc is tested late in the writing process - all a writer or usability consultant can do is spruce it up a bit. It helps, but it could have helped a lot more if usability (of software interfaces or documentation) was considered, researched, and tested much earlier.
Ok, so we cannot agree. It is ok, waste no more time with me.
Just to reiterate - I do agree that developers have a role on documentation projects. If the document is intended for technical users, developers have an even greater role to play. The point where we disagree though is the role the developer should have in writing docs for end-users. Some developers can write excellent docs for end-users, but because they know too much about the product, they often struggle to keep the right perspective when writing for end-users. Moreover, most developers just plain lack the knowledge and skills necessary to write great software documentation. Most don't know how to analyze an audience, perform usability tests, or design information so it can be easily understood.
