Is there a standard for describing a form in a programming specification?

Question

I'm a web programmer at a small web firm. When we have a larger programming project, I write a specification document for the client to review, make necessary changes, and eventually approve.

Our clients are not very tech-savvy, so I always include an overview of the programming, written in simple prose. I think they get that part… it's the point at which I describe the, well, technical aspects I'm afraid is going over their heads.

What I do to try to make it easier, is create a table that explains what is being collected and how.

For example, a simple contact form would include a table similar to he following:

    | Field    | Type     | Options   | Notes                    |
    --------------------------------------------------------------
    | Name*    | Text     |           |                          |
    | Email*   | Text     |           | Will ensure valid format |
    | State*   | Dropdown | US States |                          |
    | Comments | Textarea |           |                          |

I'll explain what the asterisk indicates in a paragraph above, and I always describe the field types in footnotes, the first time the field is mentioned. But, as my specifications have gotten more complicated, and the data collected has become more lengthy, I've started to wonder if there's a better way.

I've researched this (here, UX.SE, and Google in general), but I've found very little and nothing specific. Usually, the examples are for in-house documents, not for those who think websites are magic.

TL;DR

Is there a standard way of explaining form fields/database data/collection methods to a non-techie client?

Answer 1

That table is not client-ready. I understand the technical terms like “dropdown” and “textarea” but those words should never be put in front of a client. Except for the rare exception who has some programming experience, at best the client will get nothing out of it, and at worst, they will have a really uncomfortable experience and resent you for it.

I recommend you don’t use tables to explain these interfaces to your clients — instead, use an illustration. It is very standard to use illustrations in technical writing. When I wrote technical books, they were 1000 pages with 500 illustrations. If not for the illustrations, they would have been 3000 pages.

Even the most non-technical client has very likely used a Web form. So all you have to do is show them something that looks somewhat like a Web form, and they will see a Web form:

I made that illustration with Autodesk Graphic in about 5 minutes, tops, including placing it within this article. It is just a few rectangles and a few text objects. The hardest part was looking up a list of alphabetical US states that I could paste in there. Even if you don’t have any experience with drawing tools, it will still likely take you less time to make an illustration like this than it would to make a table or write a description.

You might want to put a caption “for illustration purposes only — not a final layout” on your illustration to prevent the client from thinking that is really what the final form will look like. It is meant to simply be a step up from the table you made, not to be a layout. But an additional advantage beyond better client comprehension is less ambiguity for the person who makes the final layout. The table version could be accidentally misinterpreted, but it is pretty hard for a Web designer or programmer to misinterpret an illustration like this.

So illustrations improve your specification for everybody.

Answer 2

There isn't a "standard way" to explain technical concepts to those who wouldn't understand, at least to my knowledge. I do, however, have a few techniques that you might be able to try when you have to write up a technical report in a simple way.

• Break up your report into clearly divided sections. This allows for the reader to more clearly understand what they're looking at.

• Define everything in easily understood words. Personally, I dislike looking at footnotes; it makes the document look more difficult or complex that it actually is. But the decision on where to define words is up to you.

• Generalize. If you can give a small description of how something works without going into great detail, then give it as an overview.

• If you can, use analogies and/or diagrams. Your tables probably help a lot, but make sure that they're big enough to easily read and see. Many clients likely don't want to have to think too hard about what a table is showing.

• Get help. I often pretend I'm explaining things to my mom and that helps me use smaller vocabulary and generalize technological functions.

Unfortunately, this is something that might always plague tech developers. I do have one last suggestion, although it might not be the most ideal.

• Keep your client on a partial "need-to-know" basis. Give them all of the information, but for the technical sections, leave it as complex and lengthy as it needs to be to share the information. Give them a general overview of collection methods/etc, but if they can trust you to develop a product that will achieve the intended objectives and meet the given requirements, then your job will be much easier. Offer to meet with them and go into more depth if they'd like/if you're able to, but if they won't understand it then they don't need to.