Patrick Peak

Stories and Client communication

Stories explain how a unit of software functionality. The intent is to make clear to both the developer and client how the the system is going to be different than it is now. A story should have:

1. A short unique client or project specific id that both parties can refer back to in correspondence (i.e. #104)
2. An estimate from the developer
3. Approval from client
4. A clear name
5. Be small enough that everyone both parties can wrap their heads around it.

Starting point for understand

One of the key implications if stories is that both parties need to have a pretty good understanding of what the system does right now in order to for this process to work. If developers are writing overly detailed stories when the system is still nascent, their estimates will be mediocre at best. And if the client doesn’t understand the intricacies of their own software, they won’t be able to make informed judgements about the cost of the changes.

Ids don’t need to be globally unique

Having used quite a few software tracking tools over the years, each one definitely has it’s own warts to be sure. One that is particularly troublesome variant though though are trackers that don’t assign any ids to each ticket/story/issue (or whatever a system happens to call its unit of work). Or assigns an equally useless globally unique id. 

This creates endless opportunities for miscommunication with clients. Ideally, it should be easy to write a simple email saying that issues #102, 123 and 124 are deployed to a staging server for testing. This inevitably leads to numbered bulleted lists in emails, where what #1 refers to changes from email to email.

Incoming: BrowserCMS commandline script

In 3.1, it should be a bit easier to create a new BrowserCMS project. The new gem will come with a command line script which should simplify the syntax associated with project creation. Here’s how it works.

Old 3.0 style
Instead of writing this somewhat ungainly command:

rails my_project -m http://browsercms.org/templates/blank.rb

New 3.1 style
You will be able to type:

browsercms my_project

This will create a blank BrowserCMS project, just like the first script. It’s basically just a simplifying wrapper around the rails command.

For the very lazy (like me)
And if ten characters is really just too much to type for you, the following will work as well.

bcms my_project

Modules, Demo and rails options
In most cases, developers want to create blank projects, which is what the browsercmscommand does. The two next most common use cases are:

• Creating a demo project (which contains some more detailed sample templates and data)
• Creating a module (which creates a skeleton for a packagable BrowserCMS module).

In addition, the majority of the rail’s commandline options are still available (like -d and –force), so you can still pass the same options in. Here’s some examples:

Demos for the new folks

browsercms demo_site -m demo

This creates the project using the demo application template. What we have done is overload the application template option (-m) to allow a short hand version (demo) rather than have to specify the full path.

Creating a module
The same is also true for creating modules, like so:

browsercms bcms_fancy_module -m module -d mysql --freeze

This creates a module project. Here we show off how the standard rails options work, so this project will use mysql database and freeze Rails into the vendor/rails directory, via the -d and —freeze options.

Get some help
You can run browsercms to get help on what options the command supports.

Benefits of having a script
There are few reasons why we decided to add the new script, starting with the most obvious:

• It’s shorter to type and easier to remember: Even I had to look the exact syntax for the 3.0 command, so a worst this change is about my bad memory.
• We can provide help/documentation: By having a script, we can make things more discoverable for new developers as well as provide examples/options for returning users.
• Removes the external dependancy on browsercms.org: By creating a script, we can look up and use the blank.rb template from within the gem, rather than needing to download it from the browsercms.org website
• Handle multiple versions of templates: One major problem with the 3.0 syntax is that we couldn’t make changes to say, blank.rb, without breaking backwards compatibility. All versions of browsercms were using the same template file. By using the templates packaging with each gem, we avoid the need for silly workarounds.

Requiring developers to remember which version of a template to use would be asking for trouble. The following would certainly have worked, but is needlessly complicated.

rails my_project -m http://browsercms.org/template/3.0.4/blank.rb

In Conclusion
So that’s the new command line script that will be available for 3.1. It’s available current in the master branch on github for folks to play around with. Over the next few weeks, I plan to add more articles here about upcoming features and changes from 3.1, so stay tuned.

Sketching out the BrowserCMS Roadmap (3.1/3.0)

As we have been working on some new functionality for BrowserCMS, it dawned on us that we were doing was slightly bigger than bug fixes and integrating community patches. As a result, we have created a branch of BrowserCMS based off the 3.0.4 release and labeled that 3.0-stable. 3.0 will now be maintained as a bug fix branch, primarily aimed at patching up the support for IE 7/8. I expect 3.0.5 to be done shortly.

Goals for 3.1

There a few highlights goals for what we want to get into 3.1, some complete, some in progress and others just on the wishlist. Here’s a quick overview along with [Status] of the work.

1. Upgrade the default WYWIWYG editor – BrowserCMS comes bundled with FCKEditor, and there is new version out CKEditor which is a pretty nice upgrade.  Getting a cross browser compatible spell check alone is probably worth the price of admission. There is a ‘but’ however, because CKEditor doesn’t come with an open source way to browse the CMS file repo for linking. [Done]
2. Create an FCKEditor module – This will allow developers who want to continue to use FCKeditor, for either file linking or just avoid confusing their clients. [Planned but Not Started]
3. Create a commercial CKFinder module – CKFinder is the commercial file manager designed to plug in to CKEditor. We want to explore creating a Commercial BrowserCMS module that would allow CKFinder to be used as the file browser. [Not Started]
4. Acts As Content Page – Developers should be able to create controllers that can more easily take advantage of the CMS core services, like Authentication, Authorization, Templates and error handling. This feature is a first pass, and I have few ideas on to refine this in further versions. [Done]
5. Portlet Workflow Improvements – Portlets make it easy to allow their views to be editable via the CMS UI. The challenge was that by default it was hard to refine the initial render.html.erb unless you removed the template editor controls. This features creates a new Form Helper for rendering the template editor, which is disabled by default. This lets developers easily get the portlet view how they like it and then turn on the editor with a single boolean. [Done]
6. Documentation - One of the biggest roadblocks standing in the way of productive BrowserCMS developers is the state of documentation. As part of 3.1, we are planning on focusing on improving the topical guides around the things developers touch the most, namely Blocks, Portlets and Templates. This article from some of the Django folks onWriting Great Documentation contains some good guidelines for what we want. [Not Started]
7. Command for creating BrowserCMS projects – Right now the command for creating a new project is both fairly long since it needs an application template path, and it also has an external dependency on where that template is. This makes it complicated to release new versions of the template. Ideally, we it should just be possible to type ‘browsercms project_name’ to get your project. [Not Started]

That’s probably about all I suspect we will aim for in 3.1, but hopefully this should give a better sense of where we are trying to go with the project. I’m also going to try to draw up some broader goals for 3.2 and beyond.

Let me know your thoughts either here or in the project Mailing List.

Starting off, with Rails Content Management

So after a bit of a hiatus from blogging, I’m back up and running. I plan to use the space to talk about a few things, generally on the subject of business of web software development and content management. My company, BrowserMedia, has been working on an Open Source revamp of our flagship BrowserCMS product. The new version of the CMS will be written in Rails, and is going to be designed to make business users, as well as programmers productive. Our team has been working hard on it for the past few months, and we are looking forward to releasing it soon.

More details to follow as we get closer to our release, but you can stay tuned on our Google group or on twitter (@browsercms).