: Re: Is there a standard for describing a form in a programming specification? I'm a web programmer at a small web firm. When we have a larger programming project, I write a specification document

@Eichhorn147

Vote Up Vote Down

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.

(0)

Login to post a comment!