[pmwiki-users] Fixing the documentation

[Patrick R. Michaud]

On Mon, Jul 13, 2009 at 08:23:35PM +0100, Ed W wrote:
> The rest of your email sounds like you are agreeing that it would be 
> useful to draw up a list of (probably only a few) words which are 
> "correctly" spelt as a CamelCase word and not as a spaced word?  
> We could then document that list and it would help keep the 
> documentation consistent going forward
> 
> I'm not sure what your rules are on creating new pages, so would someone mind
> starting me off with a page please?

It's a wiki, so there aren't really "rules" for creating new pages.
Just create them.  However, a good guideline is to "tread lightly"
on making significant changes to existing pages, especially if it
looks as though someone has already put a significant amount of work
into the current formulation.  At that point it's good to ask "I'm
thinking of changing this page to instead be like..." and see what
comes up.

I also think the PmWiki documentation pages now allow for "-Talk" or
"-Comments" pages where people can discuss the organization and content
of the page itself.

> Suggested list of "proper nouns" (wrt pmwiki) for that page appears to be:
> 
> * PageList (suggest this spelling since it's the current documentation
> pagename)
> * WikiWikiWeb
> * ChangeLog (see: http://en.wikipedia.org/wiki/Changelog)
> * WikiStyles
> * InterMap

Correct.

> Replies to your email:
> 
> 
>         * [[AuthUser]]  - should this be [[Auth User]]?
>         * [[PerGroup customizations]]
> 
> 
>     These look correct to me in the original.
> 
> 
> 
> Err, well yes, but my point was that the "house style" appears to be to
> minimise the use of camel case now, so things should only be spelt like that if
> are effectively "proper nouns" wrt to this project.  I can see some argument
> for AuthUser to remain as a single word (although it feels weak to me?), but
> [[Per Group Customisation]] feels much better to me than [[PerGroup
> Customisation]] (Why is PerGroup a single word?  I don't see why it should be
> promoted to a consistent camel case spelling?)

"AuthUser" is (to me) the name of the PmWiki component that handles
user-based authentication.  As such it feels more like it should be a
single word instead of two.  Phrases another way, "Auth" isn't really
a word in my book, so it doesn't deserve to be a separate one.

If the issue is the camel-casing of the word, I'd prefer to keep the
current casing because there are system-level pages that depend on the
current case.

I don't think that "PerGroup" should be treated as a single word.
I'd be happiest if the name of that page changed entirely to avoid
the use of "Per" altogether, but I've never come up with a good
answer.

Generally I try to choose page names that lend themselves naturally
to being used in a sentence, which is how we ended up with "per group
customizations".  If we can come up with a better phrase to describe
what these are, that'd probably be best.  (No, I don't have a better
phrase in mind, or else I would've used it.)

>         * [[Custom wiki styles]] - elsewhere "WikiStyles" is quite common,
>         versus "Wiki Styles" here?
> 
>     I prefer "WikiStyles" to "Wiki Styles"
> 
> Ok... This is one which is quite widely varied, but not too hard to argue in
> favour of it being "promoted" to a CamelCase word.  After a quick scan this
> word is perhaps the most inconsistently used link name, so it would be good to
> choose a house style and stick with it?

WikiStyles it is, then.

>         * [[PageDirectives]]
> 
>     I can go either way on this one.
> 
> Then can I recommend we minimise CamelCase words unless they feel extremely
> special and a core feature of the application?  Therefore lets make that 
> [[Page Directives]] ?

Agreed.

> I think actually there is a second level of consistency we can fix at the same
> time (and this has nothing to do with link styles!).  This is down to
> capitalisation of links, eg should we write:
> 
> - Page Directives, or
> - Page directives?

First, I should note that I'm reluctant to declare that it should
be all one thing or another -- the English language simply isn't
so clear cut.  If you're talking about the title of the page, then
it's probably "Page Directives", because American English 
capitalizes all words except for articles, prepositions, and 
conjunctions.  If you're talking about using the phrase "page directives"
in a sentence or within a page, then its capitalization rules depend
on the usage in the sentence:

    [[Page directives]] are special commands embedded in a wiki page ...

    The @@(:pagelist:)@@ [[page directive(s)]] is used to list all pages ...

    For more information, see [[Page Directives]].

> Can we get a second list going of anything that people consider SHOULD be
> spaced, but SHOULD be spelt in capitals?

I'm doubtful that such a list will be workable -- see above.

> I guess these "House Styles" should become a page under the PmWiki
> documentation section?  Can you start me off with a recommended 
> page name and paste in the list from the top?  

Just start creating it somewhere.  It's okay to create new pages in the 
PmWiki/ group on pmwiki.org, they don't make it into releases until
explicitly added as part of the repository (either by Petko or myself).

Pm