Wiki page structure [RFC]

[Karsten Wade]

On Sun, 2006-12-10 at 11:33 -0600, Patrick W. Barnes wrote:
> On Sunday 10 December 2006 11:14, Dimitris Glezos wrote:
> > O/H Karsten Wade έγραψε:
> >
> > I suggest a small change: to follow Wikipedia's structure to put the
> >
> > introduction right below the `= h1 =` and *after* that the TOC. Like this:
> > > = Title of page =
> > >
> > > This is a description of the page. It should say what the page is about
> > > (it's purpose) and be about 1-3 paragraphs long. Something like an
> > > introduction.
> > >
> > > An example: The Fedora Project wiki has a very low barrier to entry for
> > > editors. However, there can be a small learning curve when beginning to
> > > use wiki, and we have a number of guidelines that all editors should
> > > follow. This page provides those guidelines and a few tips to help you
> > > get going.
> > >
> > > [[TableOfContents]]
> > >
> > > == First section ==
> > >
> > > Blah.
> >
> 
> I agree with this totally.  The first shot of a page should tell the user if 
> it is the page they really want to look at.  They should know what the page 
> is and should get a few details before they start jumping to other sectiPauloSantos/Testingons 
> of the page.  The introduction should be short enough to keep the ToC readily 
> visible.

Yes, I agree with this.  It was in fact the Wikipedia structure that I
had grown to like.  However, I'd like to put it in as a rule with an
exception to drop or move the introduction.  Drop if it is not needed
(self-evident what the page is), and put a long intro after the ToC if a
long intro is truly needed.

For FDP work, we'll surely follow the rule; but I think we should have
some flexibility in general project docs.  Theory of minimal disruption.

> >   1. The "you are here" should be handled by the wiki engine and not the
> > author of the page.
> 
> I've always wondered why the "breadcrumbs" were removed when we switched to 
> the current theme.  They are really useful.  They do, however, need to be 
> kept in the header, not the content, which would be an automatic thing if 
> they were restored to the theme.

I forget why they were removed, something got broke.  Let's definitely
re-enable this.

>>   2. We could think about disabling very deep contents on the TOC (ie make
> > it include only up to level-3 headings so that it is short and sweet.
> >
> 
> Generally advisable, with possible exceptions.  If we document how that is 
> done, I think most people will do the right thing.

I think we should make the TableOfContents only display three nesting
levels and no more.  If it is easy for people to custom that with the
macro, we can make the default two nesting levels and let people add a
third level if they need.

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-websites-list/attachments/20061211/239ecc0c/attachment.sig>