Here's a usability suggestion, partly inspired by the excellent
KoalaSkin - why not put a summary of the key
TextFormattingRules right in the Edit page? This is used by
PhpWiki and
JspWiki, and it works really well IMO.
See also
UsabilityIdeas.
--
RichardDonkin - 28 Mar 2002
Would this be the link to the popup, or did Colas change anything?
Blogs sometimes have the summary as a column at the side. I recall seeing it with
http://drupal.org/, but can't find a screenshot anymore.
--
ArthurClemens - 01 Sep 2003
I think it would be a great idea to have a column next to the edit box (right or left) which summarizes all of the basic
TextFormattingRules. This should ideally be an option that defaults on; that way, as users become familiar with the markup they can turn it off and reclaim the horizontal space.
Speaking of default per-user preference settings, I think that having the edit box width setting in the default user profile is not currently useful because the default skin overrides it with
CSS. It should be removed or changed to create an important
CSS override so that if used it will actually matter.
--
WalterMundt - 02 Sep 2003
I believe it would help to show some formatting help on the edit page. Probably better not next to the edit box, users prefer to use the whole width for editing. Below the edit box is better IMO. Not the whole
TextFormattingRules topic, this would be too complex. Better something like
WikiSyntax.
--
PeterThoeny - 02 Sep 2003
Ah yes, I actually mean
WikiSyntax rules.
Using the whole screen space will address power users more that beginners - not necessarily a bad thing, as beginners most often don't stay beginners. Showing all markup all the time using up a large portion of the screen can become irritating at some point. Not sure how 'sophisticated' this should be (turning off the info).
--
ArthurClemens - 02 Sep 2003
The intention was a small amount of text (maybe 5-10 lines at most), right on the same screen as the Edit page, without needing to pop-up - not aimed at power users but at beginners who don't remember all the basic
WikiSyntax for bold, bullets, etc. I saw this originally on
PhpWiki - hit an Edit link on their wiki to see what I mean.
--
RichardDonkin - 02 Sep 2003
That's why I was saying make it an option. Beginners might like to have the help text right alongside the edit-box, so they wouldn't need to scroll to refer to it. As users become more advanced, they can simply edit a setting in their user page to disable the help and get use of the full screen width for editing.
PowerUsers will probably immediately disable the helptext, but some users would probably not mind it at all. Overall I don't think it'd hurt anything, and it might make it easier for new users to catch on to the
WikiSyntax.
--
WalterMundt - 02 Sep 2003
haha too late guys
I have this feature in
SimpleSkin
--
PeterMasiar - 03 Sep 2003
A first simple version is now in
TWikiAlphaRelease and here at TWiki.org. It simple shows the
WikiSyntax topic below the edit. The first few lines are usually visible (depending on the box height, screen resolution and font size), and are not too much in the way for power users. It could be done optional, not sure how much gain that gives.
Give it a try and let us know what you think.
--
PeterThoeny - 04 Sep 2003
This works fine. I only would suggest to give it a bit less prominence by putting the text in a table with a light gray background.
--
ArthurClemens - 04 Sep 2003
Hmm, I think a gray box makes the text stand out even more. For testing (not yet in CVS), I changed the text color to a dark gray and made the text smaller. Would that work?
--
PeterThoeny - 05 Sep 2003
The gray is still almost black on my screen. Perhaps use #555555?
One thing I did not realize before and which turns out to be a major annoyance is that the Edit page becomes unoperable with a scroll wheel. I routinely start scrolling the edit box with the scroll wheel, but when it comes to the end of the box, the whole page starts to scroll, taking the edit box with it - because there is now a large piece of text at the bottom.
So that means that help text should be moved to the top of the page. Clearly the amount of text should be reduced to a few lines. I would suggest to keep paragraph, bold, italic, bol italic, wikiword, bullet list, and a link to More formatting rules.
--
ArthurClemens - 05 Sep 2003
For me this extra help text is pretty distracting. Seems very spaced out as well. Probably more useful to new users, if there was a preference to turn most of it off on my user page I'd use it.
--
JohnTalintyre - 05 Sep 2003
I'd like to see it much shorter, about 5-10 lines at most and not double spaced (any volunteers to do a cut-down version?) as on
PhpWiki (click on
their SandBox edit link to see what I mean - if beginners want to do something not in this very short text, they can click on
TextFormattingRules (or should it be
WikiSyntax used as a popup?) to get more information.
The
HelpTextInEditPage should be configurable for advanced users through
TWikiVariables. I don't think it should be moved to the start of the page since it would be more intrusive there - if scrolling is an issue, it should be moved to the side of the page (must definitely be configurable!). However, if you put the cursor over the textarea field you can easily use the scroll wheel to scroll that part, even if most of the visible browser screen is non-textarea.
--
RichardDonkin - 06 Sep 2003
As I mentoned above, I added this feature long time ago in
SimpleSkin and you can see it live at my
Usability wiki
In
SimpleSkin, help in edit header is:
--
PeterMasiar - 06 Sep 2003
I do prefer the more verbose help instead of the morse code style. Putting the help in a sentence leaves less to question about. But the number of attributes to explain can be drastically reduced.
I have an alternative footer set up in
http://www.visiblearea.com/cgi-bin/twiki/view/Sandbox/. When editing, set &skin=help, for instance in
http://www.visiblearea.com/cgi-bin/twiki/edit/Sandbox/TestTopic1?t=1062881887&skin=help. User: CindySherman, pw: cs.
It is just a few lines, gray box to make it less obtrusive.
(Code attached here, see edit mode)
Ideas, requests, problems regarding TWiki?
Send feedback. Ask community in the
support forum.
Copyright © 1999-2024 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
- 3 spaces, numeral, space make a(n automatically) numbered item
Multiples of 3 spaces increase the indentation, single space (no blank lines) to maintain continuity.
3 -'s, 1 to 6 +'s, space make a heading
%TOC% inserts a TOC based on the headings
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> * 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:
- 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.
- 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:
Topic HelpTextInEditPage (simulated topic action row)
|
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. Ask community in the support forum. Copyright © 1999-2024 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)
-- Main.TWikiGuest - 2024-02-04
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.
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.
- 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
--
PeterThoeny - 14 Sep 2003
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 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