[pmwiki-users] Fixing the documentation

Ed W lists at wildgooses.com
Mon Jul 13 16:19:45 CDT 2009


Hi

> It's a wiki, so there aren't really "rules" for creating new pages.
> Just create them.
OK, done

Please see here and comment/disagree or whatever:

    http://www.pmwiki.org/wiki/PmWiki/StyleGuidelines

It's not yet linked from an of the main pages - care to comment where it 
would be appreciated to be linked in?

>   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.
>   

?? If you re-read my original email do you disagree that this is 
precisely what I did do?  If not then fine, but I still claim that this 
is exactly what I did do having started down the path of making some 
changes to the docs

> 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.
>   

Understood - in this case it's a site wide "talk" and I needed a more 
immediate answer so I thought that the mailing lists were the best option?

> I don't think that "PerGroup" should be treated as a single word.
>   

I agree - *that* is why it was highlighted in my original example.  I 
would agree with you that it should be spaced

>> 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:
>   

Agree - however, if you ever write professionally then you are usually 
be given quite strong house rules on what is the "recommended" styling 
for various situations.  Especially where there are multiple 
contributors it seems to make sense to offer an opinion over the general 
case (without limiting the authors creativity in special situations)

Note that in general the documentation *is* tending to implement it's 
own form of style guidelines and in general links seem to be fairly 
consistent (quite possibly due to diligent maintenance by Petko?).  This 
thread started though because a few seem to be vacillating between 
several styles

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

Actually I think you just did it!  I agree it's going to be only a 
guideline, but a guideline sets a precedent and it should find it's own 
way from there.  At least an opinion is offered and one can start from a 
known position.



Regards

Ed W
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20090713/39336fd3/attachment-0001.html 


More information about the pmwiki-users mailing list