The merits of documenting what you’re going to do before you do it are myriad, and I’m not going to preach to the choir on that topic. What this article is going to focus on is how to structure your document, and what content should be included so that you provide as much value to the business users as possible without overloading the document with technical “jibber-jabber” that will prevent others from reading it.
I’ve been writing functional specs for over 15 years now, and the most successful ones have the following traits:
You must provide a concise section on what the business purpose of the application. This serves two purposes:
There should be no technical terms, diagrams, geek speak, or technology-related information. From your interviews with your customer(s), you should clearly explain the end result of the project will be.
In this section, you should briefly explain how this project will help them solve a specific business problem, how it will make them money, or improve a process. This will be documentation of the information provided to your from your customer. During your interviews, you will hear what the customer expects to gain from the project.
This is where you go hog wild with your technical implementation plans. You need to break this section down into sub-section related to each specific functional area of the project. In each section, provide a screenshot or wireframe showing how the UI is planned on being implemented. Detail what information will, and will not, be shown on each screen. Explain how the user can expect to interact with the information on the screen.
Fairly self-explanatory. Ensure that you break this down to match each functional section that you have in your deliverable documentation. Do not provide a lump sum, because breaking it down will allow your customer see how the project will progress and how long before he/she can expect to see new demos of the project.
If the project calls for a new technical process to be in place in additional to the actual application UI, you need to document it in this specification as well. This section, in contrast to most others, should be very technical and detailed.
Examples could be new backup procedures, hardware interaction, or process workflow.
If the technical process is replacing an existing one, clearly explain the current process so that your customer can easily understand the benefits of the new one.
As you are authoring your specification, you rarely get all the information you need at the moment of the first revision. Provide a section where you can list any questions, or missing information, that still need to be resolved. Remember, a specification is a living document and is only set in stone once everyone signs it.
Sometimes you have a customer that is looking for guidance on what technologies should be used to implement the project. If you are introducing new technologies or languages to your customer’s environment, provide some summary information in a separate section.
Specification documents can be small – as little as 4 or 5 pages – or they can be huge. It all depends on the scope of depth of the project.
Here are some more articles that you can read to help you when creating a specification.
As children of the 80′s, my wife and I often sing songs by Journey, Loverboy, Def Leppard, or Bon Jovi about something that’s going on in our lives.
This holiday, we traveled back home to see our families and spent 5 days total up north. It was a great trip, but we were dreading the drive home. For some reason, the trip from Pittsburgh to Nashville always has some complication that causes it to last 11+ hours. Last year, the trip took us over 13 hours and elicited a comment from my wife that we would never do it again (paraphrased and cleaned up).
Well, this year, the trip back had its own theme song.
The Glamorous Life by Sheila E
Our oldest got some kind of stomach virus and threw up for the first few hours. She went through four outfits and at one point, I had to take her into a McDonald’s bathroom in the middle of nowhere in Ohio and wipe her down from head to toe. When I came back out – covered in orange and red puke myself – my wife was feeding a bottle to our youngest in the parking space next to ours because the smell in the truck was unbearable.
We just looked at each other and started to laugh, and she made the comment, “Well don’t we lead the glamorous life?”
With many developers these days writing web applications using popular Javascript libraries (e.g. Prototype or jQuery), many find themselves having to work with data objects in Javascript to enhance the user experience.
In a recent project, I was implementing a screen that required many popup dialog boxes, related Ajax calls, and periodic status updates to ensure a slick interface to the users without the need for any screen refreshes.
Without going into the nitty, gritty of the business reasons behind all the doo-dads I was creating, I reached a point where I needed to take ColdFusion queries and convert them to Javascript objects in order to push data from function to function.
To avoid further confusion, this function is simply a customization of the existing toScript() function available in ColdFusion (you can see I use it in my code below). What this does is allow you to customize the structure of the resulting Javascript object.
<cfcomponent displayname="QueryToObject" hint="Converts a ColdFusion query into a simple Javascript object" output="false">
<cffunction name="convert" displayname="convert" hint="Converts a query to a Javascript object" access="public" output="true" returntype="void">
<cfargument name="queryName" displayName="queryName" type="Query" hint="The ColdFusion query to be converted" required="true" />
<cfargument name="objectName" displayName="objectName" type="string" hint="The name of the resulting Javascript object" required="true" />
<cfargument name="idColumn" displayName="idColumn" type="string" hint="The unique identifier column of the query to be used in the Javascript object" required="true" />
<cfset var local = structNew() />
<cfset local.jsMappingStruct = StructNew() />
<cfprocessingdirective suppresswhitespace="true">
<script>
<cfloop query="arguments.queryName">
<cfloop from="1" to="#listLen(arguments.queryName.columnList)#" index="local.c">
<cfset local.colName = listGetAt(arguments.queryName.columnList, local.c) />
<cfset local.cell = arguments.queryName[local.colName][arguments.queryName.currentRow] />
<cfif isDate(local.cell)>
<cfset local.cell = dateFormat(local.cell, "mm/dd/yyyy") />
<cfelseif isNumeric(local.cell)>
<cfset local.cell = val(local.cell) />
</cfif>
<cfset local.jsMappingStruct[local.colName] = local.cell />
</cfloop>
#toScript(local.jsMappingStruct,arguments.objectName & arguments.queryName[arguments.idColumn][arguments.queryName.currentRow],true,false)#
</cfloop>
</script>
<cfreturn />
</cfprocessingdirective>
</cffunction>
</cfcomponent><cfset createObject("component", "utility.data.converters.javascript.QueryToObject").convert(steelers, "steeler.number_", "jerseyNumber") /><script>
steelers.number_43= new Object();
steelers.number_43["first_name"] = "Troy";
steelers.number_43["last_name"] = "Polamalu";
steelers.number_43["position"] = "Safety";
steelers.number_43["nfl_ranking"] = "1";
</script>