1STC India © 1999, Cisco Systems, Inc. Engineering Education Tell me something I don’t know

2STC India © 1999, Cisco Systems, Inc. Mission statement “ ” We envision to proactively fashion resource-leveling materials to allow us to efficiently promote multimedia based intellectual capital to meet our customer's needs

3STC India © 1999, Cisco Systems, Inc. Provide Cisco IOS programmer documentation. Programmer’s guide API reference Architecture reference Device driver reference Platforms and porting guide

4STC India © 1999, Cisco Systems, Inc. User, reference, and getting started manuals. Product web pages and FAQs Automated doc and updates in HTML

5STC India © 1999, Cisco Systems, Inc. Writing for engineers Just when you make ends meet.. they move the ends.

6STC India © 1999, Cisco Systems, Inc. Writing for engineers Get your facts straight RTFC Work smart not just hard Check the freeze dates before you write. Get a tech review done before you publish. Keep it web-based.

7STC India © 1999, Cisco Systems, Inc. Writing for engineers Know your audience Code developer or user? Talk to the programmers that use your book. Work with engineering to meet their needs. Use disclaimers Draft copy only For Internal use only

8STC India © 1999, Cisco Systems, Inc. Router Router w/Silicon Switch Protocol Translator CiscoWorks Workstation Comm Server NetFlow Router Workgroup Director SwitchProbe PC Router Card Cisco Hub Server with PC Router Software- Based Router on File Server Gateway Bridge Workgroup Switch Color/Subdued Small Hub (10BaseT Hub) 100BaseT Hub CDDI/ FDDI Concentrator PC Adapter Card Networking

9STC India © 1999, Cisco Systems, Inc. Thinking out of the box Throw a fit! Ask nicely Bribe them with beer Find another job Go on vacation Threaten them with management Check out other information sources Stop production Throw a party Start a doc competition Start a departmental war Hire engineers to write Write fiction Join a rock band Learn to decipher code Eavesdrop Give them a tee shirt

10STC India © 1999, Cisco Systems, Inc. Using DocX Do you C it? DocX is a tool that automatically generates HTML documentation from the source code.

11STC India © 1999, Cisco Systems, Inc. Understanding DocX Read source code Pick up function descriptions Generate documentation

12STC India © 1999, Cisco Systems, Inc. Automating documentation 1.The engineers enter function description, arguments, usage, and examples in the source code. 2.DocX reads the source code marked with specific tags, picks up the descriptions, and creates a text output. 3.We run a script every week to convert the DocX output into HTML.

13STC India © 1999, Cisco Systems, Inc. DocX Example /* edt: * * my_api_function_1 * * use: * my_api_function_1 is used by xyzzy * process to supply a fake * random number. The number is used * as an authentication code. * * return: int * Returns the square root of x divided by y. * This value is used by the xyzzy process * as a random number. * * argument: int x * The square root of this value serves as * the numerator. * * argument: int y * The denominator. This value should * never be set to zero. */

14STC India © 1999, Cisco Systems, Inc. /*edt: * remark My Title * The explanation of the chapter * goes right here and spans many * lines. It will appear as a block of * text at the start of my chapter. * * Title: Second paragraph * More text goes in here. This is * the second paragraph. It is separated * from the first paragraph by the title line. * * Title: * This is the third paragraph. It appears * without a title because the title line is * blank. */

15STC India © 1999, Cisco Systems, Inc. Bleating on about DocX DocX uses embedded documentation templates. A special edt tag differentiates a DocX template code from a C comment DocX provides many special tags for different purposes. To create DocX documentation: 1.Place your APIs in the /include header files. 2.Enter the embedded doc template code /*edt 3.Enter the default chapter name. 4.Enter the descriptions, usage and examples between /*edt and */.

16STC India © 1999, Cisco Systems, Inc. Keeping it simple Use standardized templates. Establish consistent use of layouts. Provide skeletal frameworks and examples.

17STC India © 1999, Cisco Systems, Inc. Getting there Provide multiple document delivery: Web PDF Print Frame Viewer

18Presentation_ID © 1999, Cisco Systems, Inc.