[pmwiki-users] Re-thinking Intro to markup pages

[Sandy]

Kathryn Andersen wrote:
> On Wed, Feb 18, 2009 at 10:07:19AM +0100, Peter Bowers wrote:
> [huge snip]
>> Back on topic ... does the idea of 2 pages clarify things?   (Assuming it
>> was implemented in a way that actually works.)  I'm thinking these pages
>> won't get updated very often at all and so the potential issues of (1)
>> keeping them in sync and (2) having two pages to update are probably pretty
>> moot points...?
> 
> I dislike the idea of two pages because it makes it harder to maintain,
> and it's hard enough to keep the pages up to date as it is (if it were
> easy, we wouldn't be having this discussion about refactoring them in
> the first place).

I vote for two pages. One for things new users think are common, like 
links, and a second for "Wow! I didn't realize it could do that too!" 
stuff. The full list is too overwhelming for a new user. Best bet is to 
find a new user and see what they try to use in the first twenty 
minutes. Makes sure the pages link to each other clearly.

> I also dislike the idea of forbidding the (:markup:) markup from the
> BasicEditing page, or any other page.  As a user, I love the way the
> PmWiki documentation shows examples of the markup and the result right
> next to each other.  Examples make the use of the markup clearer, and
> having them right there on the page makes it more convenient.  Looking
> at another page and/or having to look at the source of the page is
> decidedly INconvenient, IMNSHO.

I agree here. (:markup:) is required!

When looking for codes to make a "bulleted list", it's faster to scan 
down the "results" column and see a bulleted list than to remember what 
it's called, or to read every entry to see if that's what I'm looking 
for, then click to see another page to see if it really is what I'm 
looking for.

The (:markup:) code makes it very easy for the documenter to show both 
code and results, and ensures that the same code is used in both 
columns. (Very frustrating if the wiki-code I try to copy has a typo!)

New users shouldn't even see the (:markup:) command. They should just 
see the results. If they are reaching ahead and use "?action=source", 
then they're ready to say, "Hey, what's that word in brackets mean?" and 
type it into the search box. (:markup:) was one of the "programmer had 
great foresight" moments for me.

Sandy