The Savvy CMS – CFEclipse.org Makeover – Part II
When we last left our Savvy saga we were facing installation. Again the great documentation made installation a breeze and sums up the steps required nicely:
Savvy CM installation is very easy. There are no installation programs to be run on the server, instead you copy your files to the web server, modify the includes.cfm file with the correct information for your installation, register the database in ColdFusion, then upload your templates.
There are a few things you need to consider. Savvy includes an application.cfm file so if you are installing Savvy into an existing application (which is possible) you need to take some additional steps in order to allow the use of the Savvy application.cfm. Again these are outlined in details in the online docs.
Next you modify a file, includes.cfm, in which you define you datasource, some path information, site name and description and some other general settings. Next you run a diagnostic utility which will check your configuration, verify your datasources and warn you if you need to fix anything. If all looks well you can then use the same diagnostic page to create your database.
The few glitches I encountered during installation and configuration were all covered in the documentation.
Once you have Savvy installed and configured the next step is to create a template!
The Savvy CMS – CFEclipse.org Makeover – Part I
April 4, 2008 by Jim · 3 Comments
When I originally decided to revamp the CFEclipse.org site I knew I wanted to use a CMS. I looked around and evaluated a few of the free versions but the available options were either too simple or overly complex. I was looking for something in the middle.
One of the blogs I frequently read is Joshua Cyr’s and at some point I noticed he worked for Savvy Software.
I spent some time digging around the Savvy site. I was especially impressed with the level of documentation they had available online as well as the video tutorials they had created which covered all aspects of the CMS – covering everything from installation, administration and general use.
Another concern was if Savvy would run on the CFEclipse server (Linux with a MySQL back end). A quick look through the online docs and I found the system requirements:
- OS: Windows 2000/2003 , Red Hat Enterprise Linux AS & ES 3.0 or 4.0, SuSE Enterprise Server 8 or 9, Sun Solaris 8+, OSX 10.3.9+
- Database: MSSQL, MySQL
- ColdFusion MX 7 or Higher (see www.adobe.com for ColdFusion requirements)
I also checked out Joshua Cyr’s CFMeetup presentation on Savvy.
Impressed I contacted Joshua to see if Savvy would be interesting in donating a copy for the CFEclipse site. Joshua indicated several of the Savvy staff used CFEclipse and that Savvy would be happy to donate a copy. I soon had a copy of the software to install!!
Next… Installation!
CFEclipse.org Redesign
March 14, 2008 by Jim · 9 Comments
I just launched the ‘new and improved’ CFEclipse.org site this morning!
The old site was a bit difficult to update and the content was getting a bit outdated. The new site uses the Savvy CMS and is now much easier to maintain. Savvy also provides very granular permission controls so if someone wants to volunteer to maintain a particular page or section, we can allow that kind of access.
I’ll be fixing a few things here and there and updating some of the older content as time permits. If you see any typos, busted links or have any other suggestions let me know!
I’ll also be doing a few posts about the Savvy CMS. They kindly donated the software for the CFEclipse site and I’ll blog about my experience building the CFEclipse site.
Why Is Documentation So Hard?
January 31, 2008 by Jim · 5 Comments
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?
Twitter
Follow me on Twitter: @thecrumb
