TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
D~-----Original Message-----
D~From: Emma -dot- Cuthbert -at- wwa-sysmed -dot- com
D~
D~As a side-effect, my manager has asked me to look at new and
D~emerging ways
D~of documenting code.
D~He's directed me towards Document! X and javadoc as a
D~starting point.
D~Has anyone used these or similar technologies? What was your
D~experience?
D~Can you recommend any online learning resources?
I'm investigating Doxygen, which is similar and FREE. Document generating tools seem to require a different approach for writing.
Because the documentation content is encapsulated within the code base, you have to edit the developers comments in their code, and even create your own. Therefore you must negotiate a method of accessing the code, or a copy of it, to edit that is both safe (you won't be able to corrupt the code) and comfortable for the developers.
You should cultivate your relationship with the developers to a point where you can be consider part of the developer team.
If the development has bought into the idea of automatic document generation, then you can provide a good value-add by becoming the guru of the tools and tag language used for this.
- Become the expert on the document tool/method that the developers will ask questions of.
- Set up the templates for using the document tool/method
- Define what information the developers should provide
- Provide EASY guidelines for the developers to follow when they insert comments
- Get involved in code reviews so that you can be the "comment cop".
- Don't harrass the developers about commenting correctly. Take on the role of ensuring that they provide all the required information, that it is unambiguous, and formatted correctly. You should worry about that, so that the developers are free to develop; not learn how to properly tag code for the document template.
Although this sounds all well and good, it is yet untested. This is just what I am hoping to do as we incorporate doxygen into our approach...
This is a relatively new thing to technical writing. But I believe it is important for writers to learn, and a smart way to develop and document code. I've seen resistance from writers when first exposed to it, which I think is politically dangerous for them. It can be scary because it involves getting involved in the scary looking code. Well, good. You should know the languages that your documenting APIs for. (These tools are basically used for API documentation, not application documentation.)
If your development group goes this way and you don't embrace it; that could lower your karma with that company. On the other hand, by becoming an expert with this approach, and taking as much initiative with it as you are capable of, could very well increase your value to your development team. And that's a good thing.
David Neufeld [ Lead Technical Writer - Wireless ]
Spectrum Signal Processing Inc.
t 604.421.5422 // f 604.421-1764 mailto:dave_neufeld -at- spectrumsignal -dot- com
www.spectrumsignal.com
Confidential information may be contained in this message. If you are not the addressee indicated in this message please destroy this Message and kindly notify the sender by reply email.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
