I need to create a text describing an online survey that can be easily edited by non-techies.

I know you have probably already considered these issues jZed, but just for the sake of posterity:

Use YAML (and/or another pre-existing well-known syntax)

Thanks to YAML, there are now no more mini-syntaxes left to be invented. That's right, people, move along, there's nothing left do be done here, please clear the area.

Avoid The Perils of Positional Attributes

I offer no empirical data to back this up, but 'non-techies' and the keystroke-saving 'positional attributes' do not mix well. Why? Because generally: 1) non-techies are not going to read your mini syntax "cheatsheet" (although to your credit at least you provided one); 2) Those who do read your cheatsheet will not remember the parameters long enough to reliably put them in the right order; 3) The time they save in typing will be lost in the time it takes for them to: (a) repeatedly go back to you and ask where the cheatsheet is saved, or (b) pawn the work off on someone else down the line who is even *less* familiar with the project; AND 4) When the non-techies ask for "just one more feature" (and they will) you will have to (a) rewrite your cheatsheet, and (b) remember not to mess up the positional ordering (*headaches*)

I realize a lot of this is personal stylistic preference (which is why there are so many 'mini syntaxes' out there), but really ... learning the new 'mini syntax of the day' just gets old fast, non-techie or not.

By the way, personal experience has shown you may want to distinguish "$name" from "$caption" (i.e., the name of the field versus the on-screen "FriendlyName" that the users see.)

### YAML+XML Variant1 (no positional attributes, self 
### documenting and "extensible")
###
form_submit: action="/somepath/foobar-survey.cgi"
form_body: | 
    <input type="text" name="xxx" width="22" />
    <input type="radio" name="xxx" value1="foo" />
    <input type="textarea" name="xxx" width="22" height="11" />

### YAML+XML Variant2 if you absolutely insist on
### positional attributes and less typing
###
form_submit: action="/somepath/foobar-survey.cgi"
form_body: | 
    <!-- form for foobar-survey 2005-02-02 -->
    <text     props="name ;; 22" />
    <radio    props="name ;; foo ;; fee ;; faa" />
    <textarea props="name ;; Say Something ;; 60 ;; 4 " />

[download]

Mixing YAML and XML is surely unappealing, but it gets the job done, no new mini syntaxes were invented, and if you dont like it you can replace it with something else. Plus, using this style we get comments for free.

Update YAML+XML is mostly a kludge offered as a crutch for the "non-techies" who are (likely) already familiar with HTML, to which the XML looks similar. YAML can do all this by itself. Some points in this node were de-emphasized elsewhere in the thread.

In reply to Re: Generating an HTML survey form from simple markup by dimar
in thread Generating an HTML survey form from simple markup by jZed

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.