The journey has started. Let me present the official resource for CFML documentation for Open BlueDragon:
Key features:
- JavaDoc like interface
- Produced from the raw Java code; no external XML/wiki/sites to keep in sync
- Hot links to any particular function (CreateDateTime)
- See other functions/tags that fall in that category
- Quickly discover which parameters/attributes are optional
- Real look-ahead search
- See all functions/tags with their parameters/attributes
- Hot links to the OpenBD WIKI
- User contributed comments (Moderated)
We haven't finished annotating all the functions/methods yet, but even without that, you will find this an incredibly useful resource. I have even rediscovered functions I had completely forgotton existed!
In addition, the CFML app we developed for this, is already being bundled in the nightly build in the web-app folder. So you can even run your own internal documentation, complete with your own private notes.
We are annotating functions and tags as and when we get time, and already 80% of all the functions have been completed. For me, this is 10 years too late, for that I apologise. But we are here now. Never again will the documentation not match the implementation.
This is great -- not that it's just available via the web, but it comes bundled with the engine so it is available locally. Sometimes it's hard to get documentation on something if you're not currently tethered to the internet at the moment.
I've always thought it was strange that documentation in the CFML engine world is an "after" process. This approach is prone to error either from exemption (forgotten notes) or too much time elapsed. Unless you're a code maverick and dig around the CFML engine source code, documentation is the only way for people to understand new features and actually use them. Only after they are used do people find ways to improve them.
I hope to blog more in the future about open source, licensing and the world of CFML open source which I believe is currently in a positive flux. So check back often or subscribe to my RSS feed.
No comments:
Post a Comment