Ideas, requests, problems regarding TWiki? Send feedback
Copyright © 1999-2009 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.

-- ArthurClemens - 06 Sep 2003

I prefer the Morse code style, although I'd add a few more items:

• A sentence like "Use a blank line to separate paragraphs"
• Then cover a few more things like bulleted and numbered lists, headings, etc. — some samples (maintain single spacing as much as possible):

• 3 spaces, colon, space make a bulleted item

1. 3 spaces, numeral, space make a(n automatically) numbered item

3 -'s, 1 to 6 +'s, space make a heading

As an experienced user, the long page of help is somewhat annoying — if it stays that long I'd like to have an option to turn it off.

-- RandyKramer - 06 Sep 2003

Remember that the help text is for beginning users, who perhaps have little or no experience with TWiki (or Wikis in general). Help information presented in morse code style will turn a new user off - just one more thing to decipher. Too much information is confusing too, and most information presented currently at the bottom is addressing already more experienced users who can find the popup information by themselves.

If the amount of information is not that much, does not take too much screen estate, it will not be necessary to have it turned off for experienced users.

The difficulty can be to find a minimum set that will get most new users started.

-- ArthurClemens - 07 Sep 2003

Well, when I have the opportunity, the first piece of advice I give to new users is to at least separate paragraphs with a blank line. I tell them that at least that way it is clearly readable (rather than one long run-on paragraph).

I tell them that more formatting can be learned as they go along (by examples they see, for example). And that others can "improve" the formatting of their text in the "wiki way".

The next thing I tell them is to try to include headings, but don't worry if they don't know how to format them — just treat them as short paragraphs and somebody else can add formatting later if they don't yet know how.

Then I tell them that formatting headings simply requires "---+... " at the beginning of the (heading) line.

Then I tell them (for clarity of writing) to consider presenting individual points as bulleted or numbered lists (hmm, I didn't follow my own advice here ). If they don't know how to format the items, I tell them to just separate them with blank lines, they could even add a (meta)comment like "Please format the following as bullets".

Then I tell them that bullets are formatted simply by adding "   * " at the beginning of the line. (And add additional multiples of 3 spaces for deeper indentation, replace the * with any numeral for a numbered list, but keep numbered items and bulleted items "below" level 1 single-spaced for continuity.)

Personally, I think the Morse code can work for a newbie — maybe we need to get a few newbie guinea pigs?

What I haven't said so far is that I think a newbie first needs to go to a page that explains formatting (and that's why most proposals include a link to such a page) — then the Morse code on the edit page is a quick memory refresher.

-- RandyKramer - 07 Sep 2003

I've made my example a bit more dense: http://www.visiblearea.com/cgi-bin/twiki/edit/Sandbox/TestTopic1?t=1062881887&skin=helpmorse. User: CindySherman, pw: cs.

-- ArthurClemens - 09 Sep 2003

For those of us who aren't registered there, maybe this link is easier to deal with (then click edit to get prompted for username / password which can be the guest account):

http://www.visiblearea.com/cgi-bin/twiki/view/Sandbox/TestTopic1

Unfortunately, when I went there just moments ago I didn't see much — maybe the page has been edited?

Ok, I looked at Rev. 1.2, but it's not much different than R 1.1 (and I don't see any help below the edit box — am I missing something?.

• Its not in the topic, but in the edit template. To see it, use skin=helpmorse in Edit mode. -- ArthurClemens - 10 Sep 2003

-- RandyKramer - 10 Sep 2003

I like Arthur's example (try it here - username/password are above). It's suitably concise, let's implement this at TWiki.org for now and see what comments we get. It should be implemented as an included file, to simplify customising it for different sites and even webs - e.g. in the Support web it would be good to document the <verbatim> tag since that's frequently wanted.

One change I'd like is to include only the [[http://yahoo.com Link to Yahoo]] format for external links - while this was introduced after the original format, in EasierExternalLinking, it's much easier to type and to learn.

The text of the help could be a slightly larger point size - the non-bolded text is quite hard to read at least on my screen settings.

-- RichardDonkin - 10 Sep 2003

I've put in the "link to Yahoo" formatting help. If your browser reads CSS, the font size should be a bit larger now. Here is the HTML I used:

<!-- Right after %TMPL:P{"standardfooter"}% : -->
<!--
<table width="100%" border="0" cellpadding="15" cellspacing="0" bgcolor="#EEEEEE">
   <tr>
      <td><font color="#000000" size="-1" style="font-size:95%;"><strong>Formatting help:</strong>
         <ul style="margin-top:0.25em;margin-bottom:0em;">
            <li><strong>paragraphs</strong> separate with blank line</li>
            <li><strong>bold</strong> put word/phrase in asterisks: <code>*your phrase*</code></li>
            <li><strong>italic</strong> put word/phrase in underscores: <code>_your <nop>words_</code></li>
            <li><strong>bullet list</strong> 3 spaces, asterisk, 1 space: <code>&nbsp;&nbsp;&nbsp;*&nbsp;your text</code></li>
            <li><strong>links</strong> the name of the topic: <code>WebHome</code> or <code>[<nop>[http://yahoo.com This is a link to Yahoo]] </code></li>
            <li><a target="TextFormattingRules" onClick="return launchWindow('%TWIKIWEB%','TextFormattingRules')" href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%TWIKIWEB%/TextFormattingRules">More formatting help</a></li></ul><td></tr></table>
-->

-- ArthurClemens - 10 Sep 2003

Thanks for pointing out the skin=helpmorse parameter — I see it now and it looks reasonable! I would suggest that "paragraphs put blank line" be changed to "paragraph: separate with blank line" or similar.

Maybe "bullet list 3 spaces, asterisk and space ..." would be clearer as "bullet list: 3 spaces, asterisk, 3 spaces, your text" (something just doesn't look like it's rendered right on the sample page, and it uses multiple lines — or maybe that's just a konqueror problem??).

Also, I enclosed the HTML above in <verbatim> tags so it can be viewed without going to edit mode, and deleted the note that said to.

-- RandyKramer - 10 Sep 2003

(I broke your lock) Good suggestions! I updated the template and the HTML above. About the konqueror problem: I simplified the line (no more gray dots) so I hope the rendering problem is over now. Let me know.

No problem _(in this case) with breaking the lock, I usually forget to do that, and I think making releasing the lock the default may be worth considering at some point. -- rhk_

I wasn't sure it was a konqueror problem, I just know that konqueror does sometimes add more vertical whitespace than some other browsers — it looks fine now on TWiki.WikiSyntaxSummary -- rhk

-- ArthurClemens - 10 Sep 2003

I have implemented Arthur's improved help text on TWiki.org (hit Edit to try it now!) in edit*.tmpl, so that we can test this on a larger user base - this is done as a %INCLUDE% of TWiki.WikiSyntaxSummary. It's not yet in CVS or beta but I think it should be quite soon.

Any more comments on the text? I think it's pretty good already.

I'm going to try adding a line about headings -- rhk

I've also changed the "Don't forget" line below the Edit page - I really want to just have an anchor link to the help page (particularly where there are lots of WebForm fields as here on Codev), but the base tag in the template prevents this, so for now the line is just plain text (see WhyBaseTag for discussion of this tag - IMO it should be removed from the Edit template).

Also, I'm not sure the exhortation to GoodStyle is helpful for many TWikis where the main problem in my experience is getting anyone to contribute at all, let alone in good style - this could be a bit intimidating IMO, so maybe we should review that as well. I have linked it from the help text (WikiSyntaxSummary). Note that the pop-up windows work from within the Edit templates but not from the WikiSyntaxSummary page.

• Good point (to consider) about the good style link — I'm not sure it should be removed, but if it does intimidate anybody, we should consider removing it. Or maybe TWiki.GoodStyle should include an introductory paragraph to ease any intimidation (and a name change to the page as well) — a first paragraph including something like: "We'd rather have you contribute than worry about good style, but we'd like you to be aware of some of the norms of good TWiki style so that, over time, you can improve the style of your contributions." Maybe a page name like If you're new to TWiki . — rhk
  • Something like 'usage guidelines' might be a better term - this might well be adjusted (e.g. on our intranet I needed to put something in about what to use TWiki for, and what should not be included). -- RD

-- RichardDonkin - 11 Sep 2003

That's quick! One thing: I am getting a white bar now below the pink button bar, because of an extra paragraph:

<font color="#333333" size="-1">
<a name="FormattingHelp"></a>
<p />

So it looks a bit blocky. Probably you should do this:

<font color="#333333" size="-1"><a name="FormattingHelp"></a>

And you can put the links at the bottom on one line, so it is easier to click on "More formatting help" (also add a link to TWikiVariables):

<li><b><a target="TextFormattingRules" onClick="return launchWindow('TWiki','TextFormattingRules')" href="/cgi-bin/view/TWiki/TextFormattingRules">More formatting help</a></b> See also: <a target="GoodStyle" onClick="return launchWindow('TWiki','GoodStyle')" href="/cgi-bin/view/TWiki/GoodStyle">Hints on good style</a> and <a target="TWikiVariables" onclick="return launchWindow('%TWIKIWEB%','TWikiVariables')" href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%TWIKIWEB%/TWikiVariables">Advanced formatting</a></li>

-- ArthurClemens - 11 Sep 2003

I've fixed the white bar issue on TWiki.org, and put both pop-ups on a single line - feel free to edit WikiSyntaxSummary yourself, of course!

I haven't put in the TWikiVariables link as I think that should be in a TWikiSyntaxAdvancedHelp , for power users, along with somewhat different text in the Edit page for advanced formatting. (Probably WikiSyntaxSummary should be called WikiSyntaxHelp )

• Ok, but how / when does the user see TWiki.TWikiSyntaxAdvancedHelp — will choosing between that and beginners help be a preference setting? Hmm, on second thought, I think even beginners should know that advanced formatting is possible and have a quick link to help for advanced formatting (from the edit page). -rhk
  • I think the advanced help should be controllable by a prefs setting on user's home page - that way, once a user is advanced enough to have read all the basic + pop-up help, and maybe some more docs, they can enable power-user help. All formatting is specified on the pop-up window even for beginners, but the idea is to limit the apparent complexity of TWiki for beginners by having very simple initial same-page help. -- RichardDonkin

Also, the pop-up for TextFormattingRules should really be to a separate page that does a %INCLUDE% - that way the STARTINCLUDE and STOPINCLUDE would work better, avoiding the comments and doc feedback parts from being seen in the pop-up.

-- RichardDonkin - 11 Sep 2003

I added a few comments among the last four comments or so in italics and tagged with rhk.

-- RandyKramer - 11 Sep 2003

The links at the bottom are not only for beginners. The help text is, but the links are for everybody. They provide handy access to the topic that I also could have found using normal navigation, but I only think of it when I need it - that is when I am editing. So I vote again for putting the link there. Oh, and use a capital for every new link, like "Hints on good style", that makes them easier to distinguish.

-- ArthurClemens - 11 Sep 2003

Hi Peter! You reverted the use of EasierExternalLinking in the help text to use the original linking format, which I don't think is so easy for beginners to learn or use. I believe Arthur agrees with use of this link syntax, for usability reasons - did you have a specific reason for preferring the original format in this help text? Both formats are documented in the pop-up TextFormattingRules window.

About Randy's change to help text - headings are a very neat feature so I think they can just about make it in here, but that should be the last addition since aim is to keep this simple. My concern with the heading example is it's very hard for user to know what heading level they'll get.

Some comments above under Randy's italic comments.

-- RichardDonkin - 11 Sep 2003

Sorry Richard, I noticed this here just now. I was editing a topic in the Support web and noticed the ---*** heading typo, and went straight to the TWiki web to fix it. At the same time I changed the external link rule. Both rules are documented so it would not matter which one to show in the mini help. I have two concerns with the space rule:

1. It breaks the consistency rule: A user learning the [[<url> <label>]] syntax assumes that it works also with [[<topic> <label>]] which is not the case because of the WikiWordswithSpaces syntax. Follow up on this one in EasierExternalLinking.
2. Forgiving rule: IE incorrectly allows spaces in URLs. Users used to type http://domain.com/link with space instead of http://domain.com/link%20with%20space expect spaces to behave like spaces inside [[...]]. See example at BehaviourOfSpaceInForcedLink.

To avoid confusion I suggest to teach beginners the [[...][...]] syntax, even though it is harder to type.

Any reason to use all HTML for the help text? The following would save some screen real estate by placing the help text and copyright next to each other, and by using %BB% break-bullets:

Formatting help: • paragraphs separate with blank line • bold put word/phrase in asterisks: *your phrase* • italic put word/phrase in underscores: _your words_ • bullet list 3 spaces, asterisk, 1 space:    * your text • headings 3 dashes, 1 to 6 pluses, 1 space: ---++ Your Heading • internal links to other topic: WebHome or [[WebHome][home]] • external links: http://twiki.org/ or [[http://twiki.org/][TWiki]] • more formatting help and hints on good style

Ideas, requests, problems regarding TWiki? Send feedback Copyright © 1999-2009 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.

I separated internal and external links.

-- PeterThoeny - 12 Sep 2003

• I find you get a quieter image when you use the full width. The reason it is a gray block is that you give that part of the screen a meaning: you can skip that part next time once you know its meaning ( help text: not important now ). Putting the copyright next to the gray block saves screen, but makes recognition a little bit harder. To save screen space you could also put the copyright on one horizontal line at the bottom, the place where you would expect this.
• I don't have the %BB% defined in my distribution. If I use it in my template it is not converted. Is it in the main distribution?
• I advise to put "More formatting help" as one link, to distinguish it from the other bullets.

And while we're at it: can we change the copy sig line to:

This is your signature for easy copy & paste operation: (triple click to select)

This would make it easier to copy! Code:

<b>This is your signature for easy copy & paste operation:</b> (triple click to select) <dt>-- <nop>%WIKIUSERNAME% - %DATE%</dt>

-- ArthurClemens - 12 Sep 2003

I like Arthur's reasoning about the full-width grey block - I simply thought it looked better but this rationale makes sense. A single line for copyright statement would be good.

I prefer the default bullets, the %BB% ones seemed to close to the left margin.

Triple-clicking may not work in every browser, but for IE users it certainly works and is a very useful tip that I didn't know. Using edit.iejs.tmpl (JavascriptBasedEditor) by default for IE users is probably a bigger win, though.

As for EasierExternalLinking, I need to figure out a good way of doing EasierLinking (i.e. internal links) - IMO it can be, but perhaps the code will be more complex than I thought.

The 'external link' and 'internal link' are terms that beginners should probably not be exposed to, so I'm glad these are gone now. I've added the simple http://yahoo.com link to the list as well - perhaps this should be shown instead of the more complex form... in fact I think there's a strong argument for this since whichever external linking syntax is used, it's fairly complex anyway and not needed when people are beginning to use TWiki.

I've also re-worded the links item a bit.

-- RichardDonkin - 12 Sep 2003

I was going to implement the 'this is your signature' change, and drop the 'see below' part, on the assumption that most people's screens will show the start of the 'Formatting help' section. Not always true, e.g. for Codev where there are many fields, but it is true for the TWiki web and so on, and I'd think that beginners would scroll around if on a smaller screen.

However... on testing this a bit before changing things, I realise the triple-click on IE selects a whole paragraph, not a line, so it doesn't really work IMO.

I've committed the latest templates to CVS for TWikiAlphaRelease, for anyone who wants to get these. As usual, ViewCVS is 24 hours behind, so they'll be at CVS:templates/edit.tmpl and CVS:templates/edit.iejs.tmpl from 14 Sep 2003.

-- RichardDonkin - 13 Sep 2003

I did test it on IE. First I had the signature in a div, but that does not work in IE because on triple click it selects also the line below. I now put it between <dt> tags and it works fine. It does select an extra space at the end of the sig, but I think this is passed with the date, and is anyway more an aesthetic 'problem'.

You can test it on earlier mentioned location (User: CindySherman, pw: cs).

-- ArthurClemens - 13 Sep 2003

I've now implemented the signature change, hadn't tested your change exactly. I've kept the signature in bold for now, with instructions in normal font - this is partly just tradition but it also makes the signature easier to locate visually IMO. Let me know what you think.

• It's fine now. -- ArthurClemens - 13 Sep 2003

This works OK on Mozilla as well as IE.

-- RichardDonkin - 13 Sep 2003

Arthur in his TWikiUsabilityExpertRole is driving the UI. Arthur gave his blessing, so lets leave the content and look the way it is.

Small suggestions:

• We should keep content and style separated. Content should go into the TWiki web, style into the templates and skins. Better to use only TWikiML in the WikiSyntaxSummary, and to move any style attributes to the edit templates (font size and gray background). That way, different skins can chose different styles.
  • Hardwired styles crop up at more places, see HardwiredColours and HardwiredRDiffColours. We need to address this. -- AC

• The "triple click" reference is browser specific ("triple") and user agent specific ("click"). How about this:
  This is your signature for easy copy and paste:   (on IE and Mozilla, triple click to select)
• On IE I get an empty line between the edit box and the "This is your signature..." text. This is not the case on Netscape.
  • I have it too: there is an extra break just before the webform table. -- AC

Don't forget there are two embedded signatures in the iejs SKIN (i.e. the JavaScriptEditor ). Don't think they effect this topic, but might be of interest.

I think the help looks good now and is of good length.

-- JohnTalintyre - 14 Sep 2003

Comments added -- AC -- ArthurClemens - 14 Sep 2003

Opera also has the extra line before the web form... Now fixed, I hope, for all browsers, by removing the extra <br /> before the FORMFIELDS line.

I've also put Peter's wording for IE and Mozilla in edit.tmpl and edit.iejs.tmpl - even though this JavaScript-based template only works in IE anyway, a TWiki user can end up using it from another browser if iejs is configured in their preferences.

There's an argument for pointing people to 'click the Signature button above' in this skin, and deleting the two lines about the signature - why run the JavascriptBasedEditor (iejs) and use the older signature copy/paste approach? The only problem is that Opera and Mozilla users sometimes need to 'say' they are running InternetExplorer to work with some sites, breaking iejs browser detection - this is why I'm seeing the iejs buttons even though I'm using Opera. So we should probably leave this bit in even for iejs...

-- RichardDonkin - 14 Sep 2003

Is it worth saying that you can drag and drop the signature to the textarea once it's selected? This works on IE under Windows, I don't know about any other browsers/OS's.

-- SamHasler - 16 Sep 2003

The extra space that gets copied is because there is a line return in the template between the </dt> and <br /> which it treats as whitespace. Make the line end </dt><br /> to remove it.

-- SamHasler - 16 Sep 2003

On Mac OS X, drag and drop works in Safari, but not in IE and Camino.

-- ArthurClemens - 16 Sep 2003

I made some small improvements here at TWiki.org and will check it into Alpha after getting the blessing from our usability expert Arthur:

• The signature is now in a table, tripple click works now as expected
• I moved all presentation formatting (background color, HTML markup) from the WikiSyntaxSummary topic into the edit template. The topic has now only bare-bone TWiki formatting. The edit templates and skins can now control the look of the text.

Question: Do we really need the "Formatting help:" title? I suggest to remove it to save screen real estate; it should be obvious with the "See below for help in editing this page" text.

-- PeterThoeny - 26 Sep 2003

I think it helps, especially on the assumption it is aimed at beginners. What about moving the last line to the top in place of the first line, i.e., either something like:

Formatting help, more formatting help, and hints on good style:

• paragraphs separate with blank line
• bold put word/phrase in asterisks: your phrase
• italic put word/phrase in underscores: your words
• bullet list 3 spaces, asterisk, 1 space: * your text
• headings 3 dashes, 1 to 6 pluses, 1 space: ---++ Your Heading
• links use topic name or URL: WebHome, http://yahoo.com, or link to Yahoo

or any of (alternates shown for the first line only):

Formatting help (more formatting help and hints on good style):

More formatting help and hints on good style:

Formatting help, more, and hints on good style:

-- RandyKramer - 26 Sep 2003

Do we really need the "Formatting help:" title?

Yes, this small redundancy actually confirms the user, he doesn't have to guess. Like you see "Table of contents" in a book, although you could have deducted that from the context.

I do not really have a problem with putting it at the end of the list, because that is the natural reading order: scan for your problem, if it isn't in there, look further in More formatting help. Of course it is not wrong to put it on the same line as Formatting help, but it does get crowded a bit, and you loose overview. If you do want to save screen space, I would do something about the space bug (the empty line above the ul list).

The signature is now in a table, triple click works now as expected

I thought it did work after I put the string in a <dt> ?

-- ArthurClemens - 26 Sep 2003

Good point about the natural reading order.

Yes, it did work with <dt>. I should have been more specific. Using a table allows you to put the signature and explanation on the same line, saving screen space. It also removes the space at the end (just cosmetic).

I keep the "See below for help in editing this page" since the help text is not on the screen if the topic has a large form.

The change to the edit templates is now in TWikiAlphaRelease. Make sure to get the latest text from WikiSyntaxSummary.

-- PeterThoeny - 27 Sep 2003

Using a table for the signature breaks 3x-click-select in Mozilla (1.3a/Win) when the browser window is narrow enough to make the signature wrap. For all I know the same thing happens with any wrapped text though (later: yup, it does. nevermind.)

I think the formatting help hints for bold and italic should be representative samples. I personally would also add fixed width.

• bold put word/phrase in asterisks: *your phrase*
• italic put word/phrase in underscores: _your words_
• fixed width put word/phrase in equal signs: =your words=

-- MattWilkie - 29 Sep 2003

I had this too first, but why then not visualize paragraphs, bullet list, headings and links too? In the end I prefer to have simple clean layout, but it will be personal taste to have one over the other.

I think fixed width is used less often, but that can differ with each TWiki environment. Perhaps coders will use this more, but if they do they should know about verbatim too.

-- ArthurClemens - 29 Sep 2003

Arthur is right, the fixed width rule is used or not, depending on the type of users.

Here on TWiki.org and at my workplace we use it frequently, like for example in this type of documentation:

• The %SEARCH{}% understands a separator parameter to specify...

You cannot use the verbatim rule to mix fixed font text and variable font text on the same line.

TWiki's TWikiDocsStyleGuide#Text_formatting_conventions define monospaced text for:

• code snippets and listings
• API and language elements, like method and property names
• file/path/directory names
• HTML, TWikiNotation and other mark-up tags
• text to be entered by the user
• variables and placeholders

Arthus, is it too distracting to add the fixed width rule to the help?

-- PeterThoeny - 10 Dec 2003

Assumption: TWiki is used a lot by technical people. So well, yes, there is a merit in adding fixed width.

-- ArthurClemens - 10 Dec 2003

OK, thanks Arthur. WikiSyntaxSummary is updated with monospaced help text.

-- PeterThoeny - 12 Dec 2003

minor point: I think the list should be alphabetical.

-- MattWilkie - 12 Dec 2003

Agreed and done.

-- ArthurClemens - 20 Apr 2004