[pmwiki-users] Re-thinking Intro to markup pages
sandy at onebit.ca
Wed Feb 18 13:34:25 CST 2009
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
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.
More information about the pmwiki-users