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

[Kathryn Andersen]

On Wed, Feb 18, 2009 at 02:34:25PM -0500, Sandy wrote:
> 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 meant "I don't want two pages, one for the documentation and one for
the examples of the markup"; I don't particularly care if one splits up
the beginner stuff into "totally simple" and "more advanced"; what I was
objecting to was having to jump between two "beginners" pages in order
to see the description of the markup and the examples of the markup,
which is what was being proposed.
 
> 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.

Exactly!  Someone who is bold enough to do "?action=source" is not a
beginner, and thus wouldn't be frightened away by unfamiliar markup.

Kathryn Andersen
-- 
 _--_|\     | Kathryn Andersen	<http://www.katspace.com>
/      \    | 
\_.--.*/    | GenFicCrit mailing list <http://www.katspace.com/gen_fic_crit/>
      v     | 
------------| Melbourne -> Victoria -> Australia -> Southern Hemisphere
Maranatha!  |	-> Earth -> Sol -> Milky Way Galaxy -> Universe