[jboss-jira] [JBoss JIRA] (WFLY-1725) Update The Wildfly High Availability Guide

Thu Jul 25 10:59:26 EDT 2013

    [ https://issues.jboss.org/browse/WFLY-1725?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12792952#comment-12792952 ] 

Richard Achmatowicz edited comment on WFLY-1725 at 7/25/13 10:59 AM:
---------------------------------------------------------------------

Been looking at the confluence Project documentation before I make the changes and just wanted to note one thing, which seems to be messing up other projects pages. It concerns the relationship between headings (h1, h2, h3) and child pages. 

When you create a document, you can structure the document into sections using headings only. This means that your document text will be in one large page, and will make use of heading indicators (h1, h2, h3) to group paragraphs into sections. Combined with a table of contents at the top of the page, this makes scanning the content of the document and navigating via the table of contents links easy. 

But there is also a sidebar feature available; turning on the sidebar splits the page into two: side bar and a list of stuff on the left, document content on the right. The sidebar lists the child pages of the document. Instead of having all document text in one file, you can create the document from one main file plus child pages, and include (or not) the child pages using the {include: <page>} notation. 

However, this feature needs to be used with care. I have seen documents with child pages listed in the sidebar but not included in the document and sections in the document which do not appear in the sidebar. I've also seen child pages X and Y appearing in the document in that order, but ordered as Y and X in the sidebar. I find this very confusing, as I often look to the sidebar for content, as opposed to the TOC. 

To fix this, i'm going to create the document organization so that every major section of the document is a child page, and all the child pages are included in the document. This way, whether you look at the sidebar or the TOC, you are going to see more of less the same outline.

So, the main document page (Wildfly High Availability Guide) content will look like:

{noformat}
h1. Introduction
{include: Introduction}

h1. Changes Since AS7
{include: Changes since AS7

h1. Subsystem Reference
{include: SubsystemReference}

...
{noformat}

and each child page will have a similar structure.

      was (Author: rachmato):
    Been looking at the confluence Project documentation before I make the changes and just wanted to note one thing, which seems to be messing up other projects pages. It concerns the relationship between headings (h1, h2, h3) and child pages. 