Proposed Guidelines For Underlay Pages
Contents
The underlay pages distributed with MoinMoin form the core of our documentation. When viewed individually, the existing underlay pages are generally good and serve their purpose. But when viewed collectively, the pages lack a consistent format. Adherence to the following guidelines will make the underlay pages more uniform.
If there are additional ideas or better ideas, please add them.
Headings
If a page has any headings within the page, then it should begin with an H1 heading. There should be only one H1 heading defined within the wiki page content. Additional headings should use H2, H3, etc. to indicate lower levels of detail.
Not every page requires a heading. Some of the system pages such as RecentChanges do not require a heading.
Table Of Contents
Pages having more than 4 headings should have a table of contents macro immediately after the H1 heading. Pages with 4 or fewer headings may have a table of contents macro.
The table of contents macro should not have any special formatting such as embedding it in a table to float it left or right. It is the job of the user's theme to format the table of contents.
Pragmas
The use of #pragma section-numbers on to turn section numbering on, off, or start at a specified level should be avoided. Underlay pages should be neutral and not override local the wiki standard for show_section_numbers.
Navigation Macro
When used, the navigation macro should either be placed at the top of the page above the H1 heading (<<Navigation(children)>> and <<Navigation(siblings) or at the bottom of the page (<<Navigation(slideshow)>> and <<Navigation(slides)>>).
At present, the <<Navigation(children)>> macro is used only within HelpOnMacros and the <<Navigation(siblings)>> macro is used only within the 4 subpages: MonthCalendar, MailTo, Include, and EmbedObject. These should be removed because:
the four unlabeled links at the top of the HelpOnMacros page and the 4 subpages are confusing to users looking for help
- it takes a page of reading to understand the links are examples
- it takes more reading to understand only 4 of 50+ macros are complicated enough to require a subpage
- the usage is so simple that a live example is not needed
- other than being an example, the links are not particularly useful
Embedded Navigation
Use of extra navigation links such as:
at or near the top of the page should be avoided. This duplicates the function of the page trail.
Example / Display
Pages showing examples of wiki markup followed by the resulting display should enclose the display portion of the example using a wiki parser with a CSS class of dashed -- {{{#!wiki dashed ... }}}.
Advantages:
- clearly separates the display from surrounding text
- unique highlighting, dashed is currently not used within the underlay pages
- color neutral, will not conflict with theme colors or examples using colors
- heading examples are not inserted into table of contents
= Page Title - Heading Level 1 = == Heading Level 2 == === Heading Level 3 ===
Page Title - Heading Level 1
Heading Level 2
Heading Level 3
Pseudo Headings
Avoid using Bold text to make pseudo headings when a normal heading will function just as well.
Progress
Changed most HelpOn pages on 1.9 master per the above (except for Example/Display proposal). Need to review and fix pages with:
H1s used as examples - HelpOnHeadlines
Navigation macros to show children or siblings - HelpOnMacros
WikiConfigHelp macro emits H1s - HelpOnXapian
May be FeatureRequests/WikiConfigHelpCustomization can be useful?
Discussion
A guess is about 2/3 of the HelpOn pages and about 10% of the system pages require minor changes to make them consistent with the above guidelines. Any objection to making these changes to the 1.9 Moin Master? Or should we wait for 2.0 copy?
I think we should leave 1.x branch with proper documentation, for legacy reasons. So these proposals look reasonable to me. -- EugeneSyromyatnikov 2010-03-25 06:12:49
If the above guidelines are not controversial, a better place would be to add them to the bottom of EditingOnMoinMaster and delete this page.