views:

377

answers:

7

After reading about code reviews on the web I started to wonder, are there any sites or communities out there that provide reviews of documentation and technical articles?

When working as the only author on a (hobby/open source) project or a (blog) article, I often wish I had someone to read over my work and provide some feedback. This is especially important for software documentation and articles such as tutorials and introductory texts, since I know the program/area very well I have no idea whether my explanations are understandable for someone who is not familiar with the software or topic, thus feedback from an "outsider" can be very valuable.

If someone were to review my material and provide me with some (useful) comments, I would be more than happy to help them out by reviewing some of their writings.

Note: For some types of content it would be more suitable with a per review or a review by a closed group, since the material may not make very much sense until it is presented in its final form, after the review process.

So, are there any communities of technical writers (and/or editors) out there?

Update

Maybe what I am looking for is an online forum for (technical) writers? I guess most reviews could be done one-to-one (i.e. via e-mail or instant messaging) and a special online tool would not be required, given that I was able to get in touch with people who were interested in such an exchange.

+1  A: 

I find this site very useful. I get great feedback from the answers I post here. Also; when I want a review of some code I've written, I usually boot up mIRC and head to the irc.freenode.net server.

I like your question. Bumped.

roosteronacid
This works fell for small code snippets, but I don't feel I should just ask anyone to review a 2,000 word article or a 10,000 word manual "out of the blue". I'm looking for a site that will connect me with other technical writers, for mutual exchange of feedback, comments and opinions.
Anders Sandvig
You're right. But now we're moving towards: is this at all possible over the Internet in pure text form?
roosteronacid
Why does it have to be in pure text form? I don't see why I couldn't e-mail someone a PDF or give them a link to a HTML page on the web?
Anders Sandvig
And that PDF would be the spec of the final product?
roosteronacid
Maybe a specific blog / wiki with a membership for editing? I think there would interested people here who'd participate.
David Robbins
How would you move the following onto the Internet: Person One: "then I did this, and implemented this method", Person Two: "why are passing this object by reference?"...? (Not sure I can explain it better)
roosteronacid
@roosteronacid It's not a spec. I am talking about reviewing documents like user manuals, FAQs, blog postings and other technical articles. Of course, you could use the process to review a spec also.
Anders Sandvig
+1  A: 

Maybe a new tag could be created "Code Review" and people would know right away that specific help is being requested to work through a problem. This differentiates the urgency from the other questions posted.

Good question.

David Robbins
+1  A: 

Good question.

I think I'd be interested in this, if only to help my writing. Anyone else interested?

MatthieuF
+1  A: 

I don't know of any such fora, and a I have a feeling that exactly what you're looking for doesn't exist. One problem is that a large proportion of technical writers work for companies which don't let them put unreleased documents in the view of the public -- even though doing so would likely result in a better end product. Another problem is getting people interested enough to want to contribute to a piece of writing by proofreading it. This is hard work, after all, so a lot of goodwill would be required on the part of the participants.

So what to do? You could always start a community yourself. This site has shown that with the right determination, unserved needs can give rise to entirely forms of community.

But here's an easier approach: use this site. Open a question; link to the documentation that you want to have reviewed; put a bounty on the question if necessary. With the inducement of rep points, I think that you'd have quite a few takers.

Rob Lachlan
+1  A: 

There are some commercial companies that do this, such as nSight. Finding someone who does this for a living who would be willing to do it in trade might be a little hard. Alternatively, you might want to find a university with a writing program, such as the University of Iowa, and get connected with someone in their graduate non-fiction writing program that may be willing to work with you.

tvanfosson
+2  A: 

I have a friend that uses Amazon's Mechanical Turk for exactly what you mentioned and has been very happy with the feedback. You have to pay a small amount for peoples services, but its worth it.

John Ellinwood