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.
Archived Comments
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/
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.
Wireframing, Design Templates, Prototype with DevNotes, and Fusedocs: http://www.fusebox.org/go/a...
Great ! Thanks a Lot from France
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
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.
Hire a techwriter :)
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.
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.
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.
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.
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
Cool - thanks for sharing Murray.