Documentation Guidelines-Talk
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:
It seems to me that people use many techniques for finding things in a large body of text, including a table of contents, an index and a search. One issue I see is that the page index (list of pages in alphabetical order) isn't very helpful in large page collections, because the sort is not necessarily in a useful order.
What if we had an (:index text:) directive?
For example, the pages Tables and TablesDirectives might contain
(:index Tables, simple:) and (:index Tables, advanced:)
respectively. The resulting index would look like this:
T Tables
advanced simple
An elaboration could support links to anchors:
(:index Formatting, lists=list:)
would generate a link to PageName#list
It's probably easier to add index entries to a page than to word it in a way that searches work better, as it's possible for the same page to appear more than once in the index.
I see this as overkill for small page collections, but useful for some large collections, especially documentation-style collections like PmWiki.
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 http://www.pmwiki.org/wiki/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.
We may need a new group dedicated to PmWiki-related FAQs
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:
Good FAQ example: http://www.mozilla.org/support/firefox/faq
That's what I think a well-made FAQ page looks/works like. It answers fifty questions and it's easy to use.
Importantly, it answers a few questions I hadn't thought of yet.
I don't think FAQs and wiki topics are mutually exclusive. Examples:
Q: Why doesn't PmWiki use a database such as MySQL for page storage?
A: See PmWiki.FlatFileAdvantages.
Q: How do I set up user-based passwords for my wiki?
A: See Cookbook:AuthUser and Cookbook:UserAuth.
A good FAQ page will give the reader an overview of things to watch out for. Pulling certain topics off the FAQ page will cause them to be overlooked.
John Rankin said:
The Cookbook:PageTableOfContents is designed to pick up Q: markup and generate a list of links to all the questions. When questions are very long, you can insert Christian's invisible stop (`.) and the table of contents only shows the text up to the stop, followed by an ellipsis. In ordinary text, invisible stops are, well, invisible.
If the page includes major headings to separate the Q: tags, these headings appear in the TOC.
Sidebar contents
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:
- PmWiki - for users -
- AdminDoc - for administrators
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 :
- U : User/Author of the Wiki
- A : Administration, actions which can be done from the Wiki pages
- S : System, concerns administration tasks which needs system access (FTP)
You can find an old page with these markers here: http://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.
This is a talk page for improving PmWiki.DocumentationGuidelines.
I agree. I think however that we should try and automate this process if we can. Categories is one way, (:pagelist..:) should also be useful. For instance, what if we used something like John's teaser approch? In caes you're not familiar with it, it allows you to write something like:
and results in a item like
where "This page discusses ..." is extracted from the beginning of that page. We might however need to use an extended version where we don't just take the first line of the page. Instead, we could say that each page should contain descriptive paragraph that is tagged with e.g. #desc. The teaser markup could then by default extract this paragraph if the page contains that anchor. John has already implement (some of?) this stuff, so it's more a matter of deciding that we'd like to use it.
Another method to automate the generation of these index pages would be to extend (:pagelist ..:) so that it appends a descriptive text next to each item in the list.