[pmwiki-users] Conventions at pmwiki.org (Was: Comments pages vs ...)

[Ben Wilson]

On 6/1/06, christian.ridderstrom at gmail.com
<christian.ridderstrom at gmail.com> wrote:
> On Wed, 31 May 2006, Neil Herber wrote:
>
> > At 2006-05-31  09:27 AM -0500, Tegan Dowling is rumored to have said:
> >> (:if exists {$Name}-Talk:)There is also a [[{$Name}-Talk |
> >> discussion]] page used during the development of this {$Titlespaced}
> >> page.(:ifend:)
>
> Now I'd like to partly contradict myself and say that I'd like to see more
> conventions used within PmWiki (and/or pmwiki.org). These conventions
> would be there to help things look (and be!) more consistent, making the
> site easier to use for casual users.
>
> One convention already in use at pmwiki.org is placing something like
>
>         %audience% authors (basic)
>
> at the top of each page to indicate the intended audience. The direct
> consequence of this text is that it places a note at the top right side
> indicating the indented reader. This is of course useful for someone
> taking a quick look at the page.
>
> An indirect consequence of the convention of placing the above markup on
> each such documentation page, also allows us to list all those pages, eg
>         http://pmwiki.org/wiki/Test/ListBasicAudiencePages

I like this. Below Christian mentions a second step of putting in a
description in each page. I would go one step further and query
whether we should put a (:description:) in every page, and in the page
listing he offers have a template that lists the page with its
description. That way, a more concise summary would be available in
the page list. For descriptions that have a place in the body of the
document, the author should only have to slip in a {$Description} to
avoid redundancy.

> Maybe we should try and decide on some conventions and describe them on eg
> PmWiki/Conventions?

I concur. I opine we need to reign in documentation and give it a
thorough going over before the 2.2-beta series. Along those lines it
would be good to find a set of conventions to develop/maintain
consistency. I'm sure our fellow documentation geeks would agree. (I'm
a programming geek, so no offense intended.)

-- 
Ben Wilson
"Mundus vult decipi, ergo decipiatur"