RE: Should software documenters learn to read code?

["Mark Lewin" <mlewin -at- esriuk -dot- com>]

I've always taken the view that you should have as much knowledge of the
software as you intend to impart to your target audience in the
documentation you are creating.

 

So, if you're creating a 'how to' guide for non-technical end-users, you
don't need to look at the code. You should assume, like you want your
users to assume, that it "just works".

 

If you're creating a 'how to' guide for developers, then you need to
understand the API they will interact with, not how it works behind the
interfaces, functions and properties, etc that your audience will be
programming against. Clearly then you will need to be able to read code
and get an idea of what it's doing, but you should be able to rely on
your SMEs to fill in the blanks.

 

If you know too much, the tendency is to want to share what you know.
That might not be appropriate, depending on the technical level of your
audience.

 

Just my 2 cents... ;-)

 

Mark



Disclaimer and Corporate Information This e-mail and any attachments are confidential, may be privileged and are intended solely for the use of the intended recipient/s. If you are not an intended recipient, please (a) notify the sender immediately; and (b) delete the original e-mail and your reply from your system. Unauthorized copying, forwarding, disclosure or usage of this e-mail is prohibited. No liability is accepted for damage caused by the presence of any virus.  The contents of this e-mail are provided "subject to contract". Views or opinions in this e-mail are those of the author and not necessarily those of the company. The company may intercept, copy or monitor e-mails from or to anyone using its facilities in accordance with the law.  ESRI (UK) Ltd, registered in England under company number 01288342. Registered office: Millennium House, 65 Walton Street, Aylesbury, Buckinghamshire HP21 7QG.  Environmental Systems Research Institute Ireland Ltd, registered in Ireland under company number 353903. Registered office: Riverside One, Sir John Rogersons Quay, Dublin 2.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing 
solution. Author in Doc-To-Help's XML-based editor,  Microsoft Word or 
HTML and publish to the Web, Help systems or printed manuals. 
http://www.doctohelp.com

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat