[pmwiki-users] RFC: refactored introduction to wiki markup

[John Rankin]

On Thursday, 11 May 2006 1:11 AM, Pico <pmwiki at ben-amotz.com> wrote:
>John Rankin wrote:
>> This proposal is to alter the way PmWiki markup documentation 
>> is organised, to make it easier for those new to PmWiki to 
>> understand how to use PmWiki markup.
>[snip throughout]
>> 
>> The pages are: 
>> - http://www.pmwiki.org/wiki/PmWiki/EditGettingStarted
>> - http://www.pmwiki.org/wiki/PmWiki/CharacterMarkup
>> - http://www.pmwiki.org/wiki/PmWiki/LineMarkup
>> - http://www.pmwiki.org/wiki/PmWiki/LinkMarkup
>> - http://www.pmwiki.org/wiki/PmWiki/BlockMarkup
>> 
>> One thing I would like to propose is to restructure
>> the TextFormattingRules under major headings Character,
>> Line, Link and Block markup. Would that be useful?
>
>A couple of comments about the page names, particularly as they relate 
>to a proposed documentation page I am working on, which I initially 
>called MarkupCharacters (an index style documentation organized by 
>individual markup characters, ~ ! @ # etc)
>
>1. Is it confusing to have two pages with the names CharacterMarkup and 
>MarkupCharacter?

Potentially, yes. I chose "character markup" rather than "inline markup"
on the basis that those from a work processing background will be
familiar with the idea of "character styles" and so can perhaps relate
wiki markup to what they already know.

However, I think as long as the pages contain an explanation and are
cross-referenced, hafving a page called MarkupCharacters should be OK.
>
>2. Setting aside the issue of what the page I am working on should be 
>called, should I hold off on referencing to the pages that John drafted 
>(in case the names are subject to change or reorganization)?

It's so easy to refactor wiki pages, or add (:tile:) markup, and a list
of markup characters will be so useful, that I suggest you keep going.
>
>3. Would it be better, or worse, if names were structured to appear 
>closer to eachother in alphabetical listings, for example:
>
>BlockMarkup      => MarkupBlocks
>CharacterMarkup  => MarkupCharacter
>LineMarkup       => MarkupLine
>LinkMarkup       => MarkupLink

>Ok, before you say anything, I just got it: everything is markup.  Run 
>with my suggestion and every page could start with MarkupTables, 
>MarkupTrails, etc.  In fact, the page called MarkupHandling is 
>redirected to CustomMarkup. <copied>


IMHO worse for newer readers. I chose the names so that they produce
readable sentences: "there is a choice of [[line markup]] to give
pages structure" -- in general, I prefer "natural" page names.

Sometimes, I write what I want to say first, then go back and put in the 
links. That way the right names can emerge from the context.

>Or not.  Pages should be clustered by their subject matter, e.g. 
>pagelists, tables, etc, not by their organizational scope or format, 
>e.g. index.  Note, however, that we still have some pages organized by 
>their audience or levels, e.g. basic editing, basic variables, which had 
>made me think that perhaps John's pages should be similarly organized as 
>Basic..., or Introduction...  But that clustering can be done elsewhere, 
>by categories or documentation index pages. <copied>

Yes, IMHO it would be better to put all the pages in the [[!markup]]
category and use natural names.

>
>I note that John has been a proponent of similar views in the past, see
>http://www.pmwiki.org/wiki/PmWiki/DocumentationGuidelines-Comments
>and this view seems to be reflected in the way that documentation for 
>tables has eveloved:
>
>AdvancedTables  => TableDirectives
>SimpleTables    => Tables
>
>4. Is there a better name for the draft page I am working on (an index 
>of markup characters), like MarkupCharacterIndex, or 
>IndexOfMarkupCharacters, or...  (Which suggests whether index pages 
>should be clustered by names)

FWIW I like IndexOfMarkupCharacters.


-- 
JR
--
John Rankin