Ask the Crowd: Documentation

This post is more than 2 years old.

Brian asked:

I am in the documentation stage of my web application - yuck! I am curious what others use to create documentation (user, developer, etc) for their ColdFusion web applications? I know that the CFCs are self documenting, but are there any parsers that you are aware of that take care of regular CFM files? I have glimpsed at docBook, which seems to be popular in some circles. Do you know of a ColdFusion community documentation standard (tools, format, etc)?

Woot, something to talk about besides climate change. I labelled this blog entry "Ask the Crowd" as I really don't have a great answer. I'll explain what I do and I hope that my readers take up the challenge and share their thoughts as well.

So let me address your smaller questions first. Am I aware of any CF parsers for documentation? Back in the old days I wrote support for UDFDoc. This was a script that would parse comments in CF UDFs and generate HTML docs. All UDFs at CFLib still use this comment syntax which is based on JavaDoc.

As for other examples, I went to RIAForge (which has been up for days thank you very much - how come everyone emails me when it's down but no one cares when it works?? ;) and searched for 'doc' in the ColdFusion category. This returned the following results that I thought were relevant:

CFCDoc revamped - Create JavaDoc like documentation for your CFC's

CFTagDoc - Similar to CFCDoc, a documentation tool for CF Custom Tags

ColdDoc - Port of Javadoc for CFCs, that generates static HTML files for API documentation

ezDoc - ColdFusion CFC Documentor

I'll also point out cfcToPrinter - a UDF at CFLib that will take the autogenerated CFC documentation and create a nice HTML/PDF/FlashPaper version.

So I think you were mainly looking at automatic documentation generation, but I think we can, and should, open this discussion to manual solutions as well. Personally I tend to use OpenOffice to generate a Word document. I export into PDF and ship both Word and PDF versions as I figure that should cover everyone in the universe. I'm a big believer in good docs, although I honestly don't always follow my own advice. I've tried to ship good sets of docs for my larger open source applications, but for some of the smaller ones I let the CFC be the doc.

Raymond Camden's Picture

About Raymond Camden

Raymond is a senior developer evangelist for Adobe. He focuses on document services, JavaScript, and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support. You can even buy me a coffee!

Lafayette, LA https://www.raymondcamden.com

Archived Comments

Comment 1 by Geoff Bowers posted on 12/12/2008 at 3:48 AM

Don't forget the CFEclipse dictionary generator! We'll be releasing an HTML doc generator for this info too, soon enough.
http://www.daemon.com.au/cfe/

Comment 2 by ike posted on 12/12/2008 at 3:48 AM

I believe the FuseBox community still uses FuseDocs although I've worked on a lot of FuseBox projects where nobody bothered with them. Actually I'd say most of the Fusebox projects I've worked on didn't have any FuseDocs, but there have been a few.

When I first started putting together the onTap framework (several years ago), I wanted something similar that could be used to describe projects independent of the particular framework or even the language in use and after looking around a bit and not really finding anything (at the time) I created an XSD for something I called Simple Programming Environment Catalog (SPEC). What was different about SPEC in particular compared to FuseDoc is that it was tech-agnostic, so there were tags and attributes for describing things like files, objects, functions, custom tags, databases and their entities (tables, views, etc) whereas FuseDocs at the time only described the purpose of the current file and its input/output (i.e. no way to describe functions, custom tags, etc).

SPEC really should have been a separate project and should have been promoted more widely but I never really did that and nobody else took up that torch either, so ultimately as of yet it's only been used to document the functions and custom tags in the onTap framework. In theory however the XSD should provide the ability to create a simple "map" of any given software project end-to-end with information about all the dependencies between objects, etc. So you should be able to use it to fuel for example the creation of UML diagrams. The down side of course is that there's not been adoption in the community.

Comment 3 by Bliss posted on 12/12/2008 at 3:52 AM

Wireframing, Design Templates, Prototype with DevNotes, and Fusedocs: http://www.fusebox.org/go/a...

Comment 4 by Xav posted on 12/12/2008 at 7:25 AM

Great ! Thanks a Lot from France

Comment 5 by Rob posted on 12/12/2008 at 10:17 AM

For my current project, I have actually downloaded and am using Canvas Wiki. I figured this way, I could just bundle the final product and all of the documentation into a single site (it is to be hosted on an intranet). This way, I also thought that the users could expand on the Wiki with various other notes and concerns, etc. as the program was adopted... Sounded like a good idea in my head, and in execution it hasn't been too bad, just have to keep remembering to go in and document the different areas as I develop them

Comment 6 by David McGuigan posted on 12/12/2008 at 11:27 AM

Adobe Fireworks CS4.

It's got the best rapid visual prototyping tools around and has the ability to share elements between 'pages', create reusable 'blueprint' objects that can be customized per-instance, and export directly to searchable, navigable PDFs for beautiful, seductive documentation. The kind that will actually get read.

Comment 7 by Gary Gilbert posted on 12/12/2008 at 6:18 PM

Hire a techwriter :)

Comment 8 by Thomas Case posted on 12/12/2008 at 10:32 PM

I agree with Rob on having an "encompasing" documentation site. To me, an application's documentation is more than just documenting the source code/api's. A wiki (or portal) site for the application does seem to be a good model to use. As to what to put into the site, I would think at a minimum the documentation should include: Installation/Upgrade instructions, Changelists, API documentation (if project includes a library of components/services that can be used separately), and a Basic User's guide, if usage is not intuitive enough, which can often be the case.

Optional documentation, to me, would include: Advance Users Guide, Requirements/Specifications (although this may be a mandatory, if you encounter requirements constantly shifting), Test Results, and Issue/Bug Tracking/Reporting.

Of course, Gary does have a good point, even if in made in light-hearted mode. If you are developing the documentation for the organization, then you may want to off-load to a good technical writer in your organization/group.

Comment 9 by Jeffry Houser posted on 12/12/2008 at 11:31 PM

I read the original post and thought he was asking for "my app is done; now I need to write docs for my user". In that case I use Microsoft word and would distribute docs as PDFs. Whether that is good or bad is open to discussion.

However, many of the responses seem to be from the stance of "developer documentation" for the pre-development stage of the project. In that case, I'll use mind maps and often use comapping.com. Freemind is a good desktop tool. I like enterprise architect for class diagrams / UML type of stuff. And at this stage, writing stuff in a word doc is not uncommon.

Comment 10 by shag posted on 12/13/2008 at 12:18 AM

I usually get me requirements through discussions. I transfer those discussions to a flow chart. A buddy of mine turned me on to using excel for this. I usually have a mock up of any gui, the flowchart of business logic, any db info (i.e. stored procs, tables, fields), and any other dependencies. Each piece of the puzzle gets it own tab. I include a db tab that has my schema layout. In excel you can place links to goto other tabs. I have a table of contents that allows me to quickly jump to any content I need.

For my release notes, I have this information in Trac. For my user documentation, I have a separate Trac site. The users aren't as enthusiastic about using the wiki to help others as I am in supporting the applications.

Comment 11 by Nathan Strutz posted on 12/13/2008 at 2:25 AM

Pretty sure I have it worst than most. My company has specific documentation standards.

New systems are fully documented:
A document for the database description - a single large database structure diagram - I use Dia - and a description every field, documented for type, column description and PK/FK/Nullability, etc.

A document for object structure, smaller object relation diagrams, also made with Dia, duplication of field descriptions from the database document. This document is typically 3 pages per aspect of the application.

Each major area of the system is given a detailed document in the repeating format, per screen, of: general description of area, screenshot with highlighted areas, description of each area including every field visible, processing logic of each exit point. These documents are easily 25+ pages

Each major area is also given a test case document, instructing a tester in how to test each and every aspect with different environmental options toggled in various ways. These documents are typically 10 pages.

There are also other documents, but I'll try not to get into them...

Small changes require me to make a service request document that explains everything we're trying to accomplish - it's about 15 pages long, and the contents vary greatly based on complexity, writer, caffeine amount, etc.

Any changes to database or screens or functionality in the application requires that we update any legacy documentation, have it re-approved by the users, including test docs re-ran, and then those are all re-published.

Comment 12 by Murray posted on 6/25/2013 at 4:19 AM

Hi Ray.

I know this is an old post and ...

I have created a new strategy for ColdDoc to produce files from CFCs for JSDuck - the JavaScript documentation system.

This allows you to produce nice self-documentation of API from your CFCs plus have Guides etc.

See my blog post for links to sample output and source code etc.

http://murrayhopkins.wordpr...

Cheers,
Murray

Comment 13 by Raymond Camden posted on 6/25/2013 at 5:21 PM

Cool - thanks for sharing Murray.