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
of the page. The introduction should be short enough to keep the ToC readily
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
> 2. We could think about disabling very deep contents on the TOC
> 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 Wade, RHCE, 108 Editor ^ Fedora Documentation Project
Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject
| gpg key: AD0E0C41