6

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?

3

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:

enter image description here

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.

  • 1
    I used a very brief example. Normally the data I'm collecting is actually for backend things like directory input with many many more fields than will fit on a standard Word doc. Furthermore, what happens when I have fields that are dependent on one another, and thus show and hide on the form? Most recently, I created a piece of programming where the item could have calendar dates or a text-based date. Choosing between the two options allowed for either two fields with validation to appear or a single field with no validation. Displaying all three fields would be confusing to the client. – VampDuc Feb 29 '16 at 15:30
  • I second @simonwhite and I would also add: use a workflow, some kind of timeline or even animations showing how the user's "story" should happen in the normal case. – Michael Mar 10 '16 at 16:50
  • Hi @VampDuc that's a good question - here I would use flow charts or other ways to visualize the user story/stories. – Michael Mar 10 '16 at 16:51
  • Be careful if you do decide to include mockups like this — the danger is that even with a disclaimer like “not final design,” the client may get distracted and want to nitpick the “design.” – Sharon M Feb 22 '18 at 21:00
1

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.
  • I agree with all you said, and I in-fact do break up everything into sections. My issue comes on the "need-to-know" part: They do need to know. For a very small percentage, the client does trust us to build what they want. A far greater amount has absolutely no idea what goes into programming, so we have to have a clearly defined scope. They are presented with a document that says, this is what you're getting, no more no less. And as for meeting with the client, that is the project manager's job, not mine. But what I present to the client is not a final draft, and is stated as such. – VampDuc Feb 29 '16 at 15:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.