Specification Writing for Non-Developers

Without waxing too philosophical, the elephant in the room about software specification writing is that is the spec is the hardest part of building software! The document is usually a living beast, and making great software requires a bit (a lot?) of back and forth between the stakeholders and the developer. A good spec for a brand new project would be as detailed as possible to get as much information about what is desired to the developer, but would still allow a bit (a lot?) of flexibility or "play" in the implementation. (Often this initial spec is written by the developer after the two parties sit down to discuss the purpose and proposal for the project. Although in your situation unless you have a developer on staff that you've worked with, you have a bootstrapping problem which is that a contractor wouldn't take on a project with no document ('spec') of what is to wanted and what is to be done!)

The truth is that the English language (or any human tongue) is insufficient for describing the high and low level details of a piece of computer-executable software (only a programming language is that detailed, and if you have written the spec in an executable programming language and solved all your ambiguities and made all your design decisions, well, you'd have the final piece of software, wouldn't you!), so the only way to "discover" the specification for a piece of a software is to build it and then update the spec during the process, or write the spec afterwards. (Not that this is always a good use of time or advisable, just that philosophically it is the only way that makes honest sense. Progressing along these lines, a good spec for a completed project would simply be a detailed user manual with screenshots and even some algorithmic explanations for the parts that are invisible to user, in case the project is handed off to another developer and needs to be maintained and extended, although this (re-writing the spec to match the final state of the project) is often neglected.) Successive iterations of the specification go from vague to detailed, as you might imagine, and the amount of time spent updating the spec depends a lot on interest, funding, stakeholder attention-span and patience, time-frame, etc.

So with that out of the way, I would say for me as a developer, starting a project, a good spec unfolds in layers. For a specification, I don't think most programmers would care a lot about format/headings, although a clean, well- (simply-) formatted document would suffice. The stakeholder should start with the requirements about the project, the rough description given you by the "boss", almost a mission statement about the purpose of the software. Explain in a paragraph something you would explain to an intelligent developer in an email, a blurb about what the software does that justifies its existence as an individual new piece of software, versus using an existing piece or pieces of software. Another wonderful thing I've run into in a good spec overview is a list of non-requirements. What a breath of fresh air, when the stakeholder is not requesting the moon, and even cares to state this, explicitly counting the ways. Saying what is outside the scope of project, up front, is just a great way to set the bounds of the project. (Steve Jobs: "focus is about saying no".)

Once you write the overview, perhaps envision how you might expect a basic implementation of the software to work, in terms of the interface you might see as a user. This part is kind of hard because you as the spec writer may not know what you want or what could even be implemented technically, but if you hire a good developer they will understand this and you can go back and forth on the design; just get something in writing and maybe even provide a few rough wireframes, as you might sketch on a whiteboard in a personal conversation pitching the requirements verbally, standing in the room with the developer. (Having something in writing allows both parties to point at the document and share/assign blame as well as explain why something is the way it is, for good or ill! Thus it is in your favor to allow the developer to help correct your spec/design by suggesting changes based on implementation details, as might occur when the developer is trying to understand your requirements and jots their own diagrams on the whiteboard during the conversation about building the software. A bad sign is if the developer says nothing or asks no questions, doesn't push back or fails to suggest improvements to the approach, etc. You want a smart developer with a bit of "you don't want that, you want this" attitude, that's what you're paying for!) Simply outline the pieces of the software as a table of contents outline and point those sections to more detailed bits later in the document.

I would say a non-developer wouldn't need to write more than a few paragraphs for each section in the aforementioned outline as those parts of the spec would really need to be fleshed out by the developer to really get the project going. (Or alternately, would be written by someone experienced in spec writing. These people exist and their career path is called Business Analyst. Heaven help you if you hire one or are one. If such an individual is smart and creative enough to really understand software, why aren't they writing it but instead spending their waking hours a go-between for stakeholders and developers? Perhaps BAs really are necessary on large projects but it sounds like anyone happy to read/write specs all day is lacking in the spark or chutzpah that makes for great software....)

A living breathing spec could be kept as a wiki page, hich means multiple parties can make changes and the history of the document is preserved. In lieu of having a wiki setup (inadvisable) you could use a shared, editable-by-both parties Google Doc (preferably with change tracking, but alternately, saving multiple numbered versions as the spec progresses). That would actually be a good sign, from the developer's perspective, that you understand that the spec should be a living document, starting its life off as a jointly-editiable document.

I would say the first responsibility of any developer taking on the project would be to take the initial draft of the spec, as explained above, and flesh it it out more, even adding mockups for the design and features -- these can be hand-drawn wireframes, or they could be wireframes using wireframe software like Balsamiq (check it out, you'd get a kick out of this), or even a newborn functionality-free, actual-GUI version of the software, built in a visual GUI layout system like Xcode on OS X and Visual Studio on Windows. A good developer will not naively assume you know what you want/need but will rather take it upon themselves to ferret that information out of you and translate it into something that can actually be built, hopefully suggesting improvements along the way since they will have unique insights and hopefully plenty of experience  (but nothing too pie-in-sky or new in terms of crazy GUI ideas or design, hopefully, also a bad sign!).

The final caveat of all this is that finding good developers is the largest unsolved problem in software engineering. If it's hard for good developers working on exciting projects to find more good developers (cf. Oblong), I can't imagine non-developers having to attract, hire, interview, filter/evaluate and keep-happy many great developers, with interesting work. And lastly, many developers might disagree with this approach to software writing and would want a spoon-fed, bit by bit spec. In my not so humble opinion, you don't want these developers, at least not on one-persion project.