PmWiki | PmWiki / DocumentationGuidelines-Talk (original) (raw)

Discussions and comments about documentation

Some of this material may be dated or superceded. See DocumentationGuidelines for current suggestions.

Overview or Index pages

There should be more overview or index pages like Cookbook:Cookbook. It is an excellent way to browse recipes of potential interest. It is not just a list of page titles (though that exists too), it actually has a few guiding words about each referenced page, and the pages are organized by topic. The page DocumentationIndex is a poorer example (but much better than nothing!) because it does not have many capsule descriptions. It would also benefit from the addition of an intended audience indicator for each item.

One of the problems I have with the current Cookbook:Cookbook page is that the sections are organized alphabetically. Thus there's really no indication as to which recipes are the most "popular" or commonly requested/installed. Some recipes I think are the best seem to get hidden in the list... but perhaps that just me.

The sections in DocumentationIndex were already intended to roughly correspond to the audiences you've identified above; it starts with information for new authors, then moves to topics of interest for more experience authors, then information for administrators. It might benefit from a split between new administrators (who just want to get things working) and administrators who want to play with the functionality a bit.

John Rankin said:

Disambiguation pages

There need to be some disambiguation pages added to the docs - that is, pages which identify and attempt to explain easily confused features. A prime example would be a page explaining the difference between userauth.php and authuser.php. That disambiguation page should have a prominent link at the *top* (not buried near the bottom under "see also") of the two ambiguous pages. The term ambiguous is used in the sense that a new user really has no basis for deciding which recipe would suit them. There is no implication that the recipes themselves have ambiguous instructions.

Better FAQ

There are some pages that need to be ruthlessly deleted or severely edited. The prime example here is PmWiki:FAQ . It has a very prominent link in the Sidebar, and it does not deliver what it promises. It may be the first and last page that many potential users look at.

One way to give the docs a consistent look would be to use consistent markup for preformatted text, such as

pre<< Here's my preformatted text More preformatted text <<

Hagan

Following the principle of DRY (don't repeat yourself), the FAQs should not repeat the info that is already living on another doc page, rather, it should be an index and disambiguator. By including synonyms in the Q, the FAQs should be searchable. For the example above, the Q/A on the FAQs About Groups page might be:

Q: How can I limit, constrain, restrict, or control the groups or group names on my wiki? A: There are several solutions on Cookbook:LimitWikiGroups.

It could be argued that simply placing this Q at the start of the referenced page would make it much more likely for a search to find the page, but that only works well when there is a single page that answers the Q. FAQ pages also offer the ability to scan the Qs, looking for something that fits your general idea of what you want to ask.

If we expect FAQ and other documentation (e.g., PmWiki APIs) to be included in the distribution, then they need to remain in the PmWiki group. I don't want the distribution to end up with lots of pre-populated groups that site admins are having to constantly work around.

If we expect these pages to appear only on pmwiki.org, then they could be placed in other groups (although I think it still makes sense for them to remain in the PmWiki group).

Hagan said:

John Rankin said:

The Sidebar menu should be revisited. Why are the Cookbook and Skins placed under the rubric "pmwiki.org"? All the rest of the "main" features are under PmWiki. Once (or if) audience differentiation is more prevalent, it would make sense to have one SideBar entry for each audience, probably pointing to a Cookbook-style index page.

...because these identify things that aren't properly part of PmWiki, or at least do not come with the distribution. All of the rest of the "main" features come with the distribution.

But the sidebar is another of those items that I'm expecting will be heavily reworked as a result of updating the docs.

A suggestion from Pierre Rouzeau

When I organised the french translation of the documentation for version 2, I separated the documentation into two groups:

When the documentation was incorporated into the main site, these two groups were fused (by pm), but the two index pages remained separated. Another translator wanted to put the indexes on the same page, because we were diverging from the original english page.

In order to ease the process of splitting pages in these groups, I have setup category markers defined as :

You can find an old page with these markers here: https://www.pmwiki.org/wiki/Localization/StateOfTranslationTemplate

Please also note that some cookbook pages are translated, and are then listed in a third page index. But this is a bit more specific to translated documentation.