[pmwiki-users] Fixing the documentation

[Patrick R. Michaud]

On Mon, Jul 13, 2009 at 10:19:45PM +0100, Ed W wrote:
> 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?

I've added my comments.  Although now that I look a bit
further I think that perhaps this belongs on
http://www.pmwiki.org/wiki/PmWiki/DocumentationGuidelines
instead.

I also would prefer to avoid examples based primarily on the word "Wiki" or
phrases containing "wiki".  Sometimes we use "wiki" as a noun, sometimes
as an adjective, and sometimes as a prefix, so it's not really a bright
dividing line that someone can point to in examples of what we're aiming
at.  I refactored the StyleGuidelines page to avoid using "wiki" in
examples (except in the places where it's the point of the example).

>       However, a good guideline is to "tread lightly"
>     on making significant changes to existing pages, [...]
> 
> ?? 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

At this time I'm not going to agree/disagree on this point nor 
try to resolve claims about who may have been following "correct
procedure" to address this issue.  The pmwiki-users mailing list 
is intended to be flexible and accommodating in terms of addressing 
issues that arise, both from newbies and experienced developers.
If someone is looking for rigid procedures to be followed in 
absolutely all cases, PmWiki doesn't have such things -- neither 
in the software nor in its documentation nor in its support forums.  
This is by design.  

In replying with the guideline I gave about "treading lightly", I 
was simply answering the question you posed, without any intent 
to imply that you (or anyone else) had or had not followed that 
guideline.  I'm not interested in assigning blame, justification, 
redemption, or absolution to anyone.  Ultimately my "conversation reset" 
was literally meant to say "no harm, no foul" to the unproductive 
track was developing in the thread and hopefully bump it to a more
productive track.  I have no desire (nor time) right now to attempt 
to further revisit or resolve the procedural meta-discussion issues 
that came about from the other trac.  I apologize to anyone who ends 
up feeling slighted or unredeemed by this stance.

So, in summary, I think that

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

is the page we want to be updating to incorporate these additional
style considerations and improvements to the documentation, and
that we should fold the very good ideas form StyleGuidelines into
that page (possibly involving a significant refactor of
DocumentationGuidelines).

Pm