On 2004.06.27, Talli Somekh <[EMAIL PROTECTED]> wrote: > So I understand IRA's frustration when he comes upon documentation and > it is written in an idiosyncratic developer-centric manner that makes > assumptions that a newbie or even non-guru doesn't posses.
I thought the primary audience for the current documentation effort is software engineers. I'm not sure what you mean by "idiosyncratic developer-centric manner", but the documentation so far (the Tcl API docs) should be, in my understanding of the audience, certainly developer-centric. It's the "idiosyncratic" part I don't understand. The beauty of having documentation on the wiki: if a newbie or non-guru finds documentation but it's not helpful, they can edit the page and ask for clarification, or a rewording, or otherwise express how the existing documentation doesn't help them understand what they need to know. Then, the community can focus their attention to find ways of better documenting whatever it is -- this reduces waste of writing excessively verbose documentation where it's unnecessary for the actual audience, and the time it takes to write that documentation. > Allow me to submit an alternative, though. It's entirely possible to > screw the idea of getting a technical *writer* and instead get a good > technical *editor*. That person will be responsible for addressing > proper grammar, structure and presentation in order to ensure that the > documentation represents both the source and the technical writer's > intentions. I'll be on the lookout for someone within AOL who fits the "technical editor" skill set and requirements. If there's someone in the community who wants to step up and fill that role, they're welcome to volunteer. The wiki is editable by anyone. -- Dossy -- Dossy Shiobara mail: [EMAIL PROTECTED] Panoptic Computer Network web: http://www.panoptic.com/ "He realized the fastest way to change is to laugh at your own folly -- then you can let go and quickly move on." (p. 70) -- AOLserver - http://www.aolserver.com/ To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> with the body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: field of your email blank.
