11g Doc Makeover: Part 2

commentin.pngAbout a month ago, I blogged about the 11g R1 documentation’s Easter Egg feature, comments. At the time, I recall thinking this was a great, easy way to engage people, but wondered if anyone would a) comment or b) reply to comments.

Color me surprised. Today, Steeve Bisson blogged about comments he made to the 11g doc, and the subsequent response from the documentation team. They fixed the errors he found and will release an updated version.

I hope he gets official credit for finding the errors. Imagine how clean the doc would be if it were user-edited, similar to the Wikipedia model, with more controls. What if people could add SQL examples? I’ve always thought there weren’t enough examples.

What about giving users points toward levels, like ACE Directors? How sweet would that be?

As many of you may know, Applications (at least the E-Business Suite) documentation is produced in pdf only. That said, here’s to hoping we can follow this model, jumping straight into HTML doc with comments.

Pretty please?

AboutJake

a.k.a.:jkuramot

10 comments

  1. I have written so many of comments in the doc (especially in sql) that I have been included as a contributor in one book! totally unexpected… My last comment, what is the difference between atan(x/y) and atan2(x,y) 😉

    Well, comments made on the productive doc cannot be corrected as fast as the beta doc, but still the author occasionally come back to me when they need more info. That’s why I always post my email address when writing a comment 😎

  2. I have written so many of comments in the doc (especially in sql) that I have been included as a contributor in one book! totally unexpected… My last comment, what is the difference between atan(x/y) and atan2(x,y) 😉

    Well, comments made on the productive doc cannot be corrected as fast as the beta doc, but still the author occasionally come back to me when they need more info. That’s why I always post my email address when writing a comment 😎

  3. Funny, I’ve send a few feedbacks on errors I found in the 11g RAC installation docs and never heard anything back.

  4. Funny, I’ve send a few feedbacks on errors I found in the 11g RAC installation docs and never heard anything back.

  5. Frederik: Contact Laurent or Steve and see if they can give you a line into the doc group, so you can check on your comments.
    Jake

  6. Frederik: Contact Laurent or Steve and see if they can give you a line into the doc group, so you can check on your comments.
    Jake

  7. Just to clarify for people like Frederik, all the comments are evaluated by the doc group, and routed to the relevant author (easy to do because it’s obvious what book someone was reading when they made the comment). Not everyone will receive a personal response, because some people submit anonymously, some people use OTN login IDs that aren’t real e-mail addresses and we only record the IDs. Some books, the installation ones in particular, are being refreshed so fast that the fixed version goes up shortly after the comment comes in. I’d expect people to receive responses more if their comment _wasn’t_ acted upon for some reason, than if the writer just verified and incorporated the information.

  8. Just to clarify for people like Frederik, all the comments are evaluated by the doc group, and routed to the relevant author (easy to do because it’s obvious what book someone was reading when they made the comment). Not everyone will receive a personal response, because some people submit anonymously, some people use OTN login IDs that aren’t real e-mail addresses and we only record the IDs. Some books, the installation ones in particular, are being refreshed so fast that the fixed version goes up shortly after the comment comes in. I’d expect people to receive responses more if their comment _wasn’t_ acted upon for some reason, than if the writer just verified and incorporated the information.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.