Rene Rivera <[EMAIL PROTECTED]> writes: > I have some suggestions also ;-) But they are all in the general > category of the existing docs needing an overhaul. I'm not sure if there > is some specific style of documents Ericka wants to tackle but there is > a desperate need to work on the content for the redesigned Boost > website. That would include some minor thinking about web design, the > structural aspects not the graphic and programming aspects, in that it > involves taking the existing docs and rewriting them into the new > website (and of course creating new docs as needed). Ericka, if you are > interested in that please contact me directly.
Well, I think that's all interesting stuff, but it doesn't require what I consider to be the key element of technical writing skill. We have a significant amount of material that's unclear or ambiguous because the people writing it are not able to fully inhabit the mind of someone who doesn't already know what we're trying to communicate. *That* ability above all is what I hope any technical writer will bring to bear on her work. I'm not saying that thinking about web design is not a valuable skill for a technical writer; I'm just just saying that, while many of us could do that and translate the documents if we just arrange the time, very few of us have the ability I described above in combination with good English language and writing skills. So, if a technical writing specialist is volunteering her time to us, I would like to see her skills fully exploited. Have the cardiac surgeon doing heart surgeries rather than playground first aid, if you will. Of course it's possible that I've misinterpreted Rene's suggestion, in which case I hope he'll tell me so. If I consider all the places in our documentation that could benefit from the sort of professional attention I've been describing, the one that causes the most problems for people day-to-day is in the Boost.Build documentation. So, in short, I like Eric's original suggestion. The next thing I would ask Ericka to do for us, if she was still interested, would be to "teach a man how to fish." That is, help us develop web pages that would consist of guidelines and other information for Boost authors wishing to write good documentation, including a totally revamped version of http://boost.org/more/writingdoc/index.html -- Dave Abrahams Boost Consulting www.boost-consulting.com ------------------------------------------------------------------------- Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys - and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
