Re: how to handle code as appendices

Subject: Re: how to handle code as appendices
From: Laura Lemay <lemay -at- lauralemay -dot- com>
To: Jill Mohan <jillemo -at- gmail -dot- com>
Date: Fri, 27 Jul 2007 09:46:01 -0700

Jill Mohan wrote:
> The challenge I am facing is how to handle the code snippets that I have
> been supplied.
>
> The customer thinks these things should appear as appendices. But I am
> looking at a lot of appendices right now and growing daily (about 12).
> Should I segment it by type of code, ex. Appendix A - Router config code,
> Appendix B: Oracle code, etc.

Over the last number of years I've been aggressively pushing my clients
away from including code in documentation at all, other than small
examples or out-of-context snippets (up to, say 10 lines or so) to
illustrate specific concepts. Pages and pages of verbatim code in
documentation, in my experience, don't get read, are a problem to
maintain, and are much more practically useful to the audience if they
are just included online or on the CD with the product and referred to
in the docs. In the books I've worked on where we've removed the big
chapters full of code, no one has ever complained.

But that's not what you actually asked. :)

In books where we did have lots of code samples it was fine to group
them together. We used a numbered code caption, similar to table and
figure captions, to describe each sample, and a list of examples at the
start of the book.

Hope this helps.

Laura


--
*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^
Laura Lemay Killer of Trees lemay % lne.com lemay % gmail.com
http://www.lauralemay.com http://blog.lauralemay.com
*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^









^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! 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.


References:
how to handle code as appendices: From: Jill Mohan

Previous by Author: Re: Best practice for technical documentation page length on a website?
Next by Author: RE: FrameMaker Graphics
Previous by Thread: RE: how to handle code as appendices
Next by Thread: Tools: So you think you know your design terms?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads