6

I'm writing documentation for some code at work and I am trying to describe some parameters that must be specified by the user. Some of the parameters are specified with one word from a list of possible choices (e.g., "true" or "false"; "ags" or "wms"; "json", "xml", or "text"). Others are more "open-ended" and the user specifies anything they'd like (parameters like this include name, identifier, URL, etc).

I'd like to describe each of these two types of parameters. Are there words that describe one as open-ended and one as multiple choice? These descriptions I'm using don't seem to do it justice. They also seem to imply there is some kind of question involved when there isn't.

Does anyone have any ideas of what words I could use in my documentation to describe these two types of parameters?

5

For the "multiple-choice", you could use "enumerated"; however, it probably makes more sense to just list the options, using a full phrase: "either true or false", "one of: json, xml, text", etc.

For the "open-ended", you could use "free-form" or "arbitrary text"; but it's likely that there are some restrictions, in which case you can probably just describe those (e.g., "up to 128 characters", "cannot include whitespace") and leave it implied that there's not a fixed list of options.

  • 3
    I've seen "free form input" a lot for this specific application. – Alex Feinman Jul 16 '12 at 17:29
2

You could draw on the relatively familiar idioms of Web forms and describe the multiple-choice parameters as selections and the open-ended parameters as text inputs.

1

When I've written code documentation I usually refer to them by their GUI widget names. Most code documentation is intended for other coders and I would assume they had a basic knowledge of the names.

Radio buttons/checkbox/drop-down for multiple choice, and text box for text.

  • Thing is, these are not GUI widgets, otherwise I would completely agree with you. These are servlet parameters. – carmenism Jul 16 '12 at 17:51
  • Hm. How does the user input them then? – Marcus_33 Jul 16 '12 at 18:05

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.