This week I’ve been tinkering with two ColdFusion CMS programs and had two widely different experiences based on the documentation for each project.
I downloaded both FarCry and Bytespring CMS. These are vastly different products - FarCry being an enterprise CMS while Bytespring caters to the ‘mom and pop’ websites.
I downloaded both and for no particular reason setup Bytespring first. There was a /docs folder included in the download.
_ReleaseNotes.txt
_ToDo.txt
ApacheLicense.txt
Bytespring_CMS_User_Faq.pdf
license.txt
readme.txt
Reading the included readme, release notes and FAQ quickly had me up and running. It took me probably 10-15 minutes to download, read the instructions, setup the required frameworks (Coldspring, ModelGlue), ColdFusion mappings and have a working demo. How to add/edit data was fairly intuitive but the FAQ PDF covered most of the basics as well. Overall a very pleasant experience.
I then setup FarCry. FarCry has been out for a long time and I was excited to give it a try. I downloaded the latest 4.x version and after unzipping it I went looking for some documentation. After going though all the directories - there was nothing. Zip. Nada. Not even a basic readme.txt.
So I went to the FarCry site. They provided several links to various sources of documentation. The download page linked to a “FarCry 4.0 Installation Guide”, the “Documentation” tab led me to a page where I could see Daily Use Guides but these were for an older version:
Note these are aimed at FarCry v2.x product platform
There were also links to whitepapers, various PDF’s and a wiki. I was overwhelmed with too many choices and it was confusing on which one I should refer to for the current version. While I did end up getting FarCry installed and running, at the end I was confused and frustrated.
I think FarCry could improve things by halting development (they just announced a beta for 5.0) and spend some time on basic documentation. They could easily condense some of the existing information scattered throughout their site and throw it into a readme.txt file included with the download. Basic installation, what do next, where to go for more info, etc.
I hate to make an example of the FarCry project. They are not alone. I use a lot of great open source software but documentation for any of it is often difficult to find.
I’m guilty of the same thing. I’m struggling to document my applications at work. Why is creating documentation so hard? How do you handle this chore? Do you write the docs in parallel with building the app? Do you build the app then write docs? How might we encourage outside users to help write documentation?
You May Also Enjoy Reading:
5 Comments
Aha! I believe the answer to your rhetorical question is closely related to the truth you seek. Everyone hates making revisions to documentation…so we write documentation when the application is complete. However, as we all know applications are never complete. And therein lies the rub.
So it looks like the only option is to write the documentation in parallel to the app. Ugh. Like anyone has time to write anything other than code. Not gonna work.
I like your suggestion. Get the users to write it. Adobe kinda halfway tried that with Livedocs. I think it was half a solution, the missing ingredient was someone on the Adobe side willing to maintain the docs and revise them in line with user comments. It would have made sense to offer a threaded discussion model as part of the view.
We hear you. The Fortress (5.0) release has a focus on a new installer, more inline help, and better documentation.
Unfortunately, FarCry is not just a CMS, but a framework designed to build web applications. Many prominent members of the FarCry community spend their time writing bespoke CMS solutions and other web applications. Typically these solutions are delivered complete with documentation — but its not necessarily documentation that is relevant or can be distributed.
One of my jobs for the Fortress release is to provide better hooks to existing documentation — of which there is lots. But as you say its currently a bit overwhelming in terms of where you start as a someone new to the framework.
Agreed. After having worked with a client to convert her site using Joomla (PHP), I was curious about CF-based CMS. So, I decide to give FarCry a tryout. Documentation was sadly lacking, and I couldn’t figure out what was the best way to get it installed. So, I consigned the folder to trash.
@Geoff - I’m going to check out the 5.0 release at some point
I certainly wasn’t pointing the finger at just FarCry! I think many times we get wrapped up in the application and forget the simple things like a basic readme.txt.
Hi,
documentation is a drag to write, but I have good experiences letting the users of the system writing the documentation. This way they get all the stuff out of the way only programmers think a user needs to know
And only write down the sutff they need foor their daily jobs.