This is my top level page. Clearly the links won't go anywhere on this
wiki, and i wouldn't presume to add it here. I'll add the content
of some of the pages in this page. Some of the names have
been changed to protect the guilty.

* [Wiki is About Links and Content]
* [Add Links to Main Page]
* [Create Knowledge Nugget Pages with Useful Titles]
* [Make Directory Pages of Links]
* [Use Conversational Page Titles]
* [Do Not Hide Content in Big Pages]
* [Pull Content Out Into Its Own Page]
* [Weave Small Pages Together To Make Big Pages]
* [Use This Wikis Ability To Make Natural Looking Links]
* [Do Not Add a Title on Each Page]
* [Make Common Variations of Words Point to the Same Page]
* [Use Just The Right Amount of Links]
* [Add Categories to Pages]
* [Create One Word Links]
* [Include References Section in Pages]
* [Use Bullets and Headers for Quick Scanning]
* [Avoid Complex HTML and Use Simple Formatting]
* [Consider Product Versions In Documentation]

!! Naming Conventions

* [Do Not Use Spaces In Page Names]
* [Use Directory To Indicate Directory Of Links]
* [Use Home To Indicate Home Page]
* [Use Sw To Indicate Software]

----
!!! Create Knowledge Nugget Pages with Useful Titles

The general idea is to create leaf nodes of information and organize them in different ways. The leaf nodes need to link to related items. Above that are directory pages that are links to other links. 

If you put useful content in large pages then nobody knows it
exists unless they happen to read the large page. If you
[pull content out into its own page] then the content exists as a 
first class entity:
* it can be seen when browsing the [page index]
* changes will be seen in [recent changes]
* another page can link to just that page
* another page can [include | TranscludePlugin] that page into its own page


Don't worry, you [weave small pages together to make big pages].
It's important to be able to present a single integrated page
on a topic because:
* a page with everything on it is often easier to read, as apposed to following links all over the place
* it can be printed


!!! Build Environment Example

A good example is the [Build Environment] page that started out
as a large html page. Then I wanted to link to just the
development source tree section from another page. Then i wanted 
to [include | Transclude Plugin] the development source tree in 
another document.

The solution was to extract development source tree section into its own
page [DevelopmentTree]. 

The [Transclude Plugin] was used to include the DevelopmentTree page
back into the [Build Environment] page. The Build Environment page still
looked like one single integrated page, yet it is made out of smaller
pages that are include to make the big page.

If you look in Build Environment you will see a piece that looks like:
{{{
<HR><A NAME="dtree">
<H1> Source Tree </H1>

[{Transclude page='DevelopmentTree', style='margin: 0px'}] 
}}}

!!! [Memory Corruption Errors] Page Example

This page is entirely made out of leaf nodes. The
[Memory Corruption Errors] page provides and index and titles for
the related content. 

This is very useful technique because we often want to reference 
individual memory errors, yet we want to present them all in one 
document as well. 

!!! [Sw Development] Directory Example

This page is a directory because it contains links to sofware 
development topics.

!!! [Sw References] Directory of Directories Example

The [SwReferences] is a directory of directories. It is a page 
made entirely of pages that are directories containing links to other pages.

See the beauty of this architecture. SwReferences serves
as a central point to see all related software links.
Yet each subject also stands a lone. Each indiviual page can be updated
at any time and the SwReferences page will always appear
to be up to date because it includes the directory pages. 

----
!!! Wiki Is About Links And Content 

The best way for the wiki to not be just another information island is for 
people to use it and for a community to build unquestioned value
both in content and links. You can say that about any
technology, but wiki has some features 
(browser based, easy editing, easy linking, simple formatting, 
visible links, searching, etc) that make collaboration more 
possible.

See [How To Organize Wiki] for more information.


----
!! Avoid Complex HTML And Use Simple Formatting 

You don't need to create complex html pages.

Wiki supports simple formatting as described in [Text Formatting Rules]. 
Clean nice looking pages that get the point across can be made with
just these simple markup capabilities. 


* Wiki's emphasis is on content, not presentation. 

* The simple markup rules make people focus on expressing their ideas, not making them pretty. Some people have found that working in this minimal medium improves their writing. 

* One of the problems with using anything more complex than text is the ability of the community to support it. 

* Using simple formatting means that anyone can easily edit pages. Many people aren't comfortable with raw HTML. 

* You can use HTML though if you wish.

* If you have pages that are already in html it may be too much work to convert them to use a wiki syntax.


----
!! Use Conversational Page Titles 

You don't have to use short meaningless page titles.
There are several strategies for making page titles.

! Page Titles Are Marketing

Page titles sell their contents. Make page titles that
will invite people to read the pages.

! Make Page Titles Descriptive

Use page titles that tell readers what the contents of the
page are. When someone is looking at [recent changes]
that should be able to tell what the contents of the page
are from the title.

! Page Titles as Nouns

A good page title is often just the name of something. For example, 
SystemStateMachine. People know when they see that name they
should see a discussion of the system state machine.


! Page Titles as Assertions

Page titles should be assertions, for the simple fact that you can 
then link to them in sentences grammatically. For instance,
"I think your grasp on the problem is wrong because ProgrammingIsNotMath," 
is a lot cleaner and clearer than saying, "I think your grasp on the 
problem is wrong because programming is not math. Please read the 
argument on IsProgrammingMath to see what I mean." Less text 
is better than more text. 

! Page Titles as Questions

Page titles that are questions, like IsProgrammingMath, invite
people to answer the question, so are an effective strategy.

-----
!! Weave Small Pages Together To Make Big Pages 

You can weave small pages together to make big pages. It's important to 
be able to present a single integrated page on a topic because: 
* a page with everything on it is often easier to read, as apposed to following links all over the place 
* it can be printed 

See [Create Knowledge Nugget Pages With Useful Titles] and
[How To Organize Wiki] for more information.

----
!! Use This Wikis Ability To Make Natural Looking Links 

This wiki has a very flexible way of making links to pages.
With some effort you can integrate links naturally into
your pages. 

See [Make Common Variations Of Words Point To The Same Page]
for related information.

!! Old Style Camel Case Links

The original link type is the CamelCase link. The problem
with this sort of link is that it is hard to read and 
doesn't flow naturally in text.

!! New Style Bracket Notation

Instead you can use the bracket ([[]) notation as described
in TextFormattingRules for links. 

!! Can Separate Words By Spaces

The wiki will squish separated words together for you so you
can use spaces between words: [[Camel Case].

!! Can Use Upper or Lower Case

The wiki will automatically convert case for you so you

can use lower case instead of upper case: [[camel case].
This makes it easy to include [camel case], for example, as
a link as part of the text of document.

!! A Link Can be a Single Word

A single [word] can be made a link using brackets: [[word].

!! Plurals Automatically Link to the Singular Name Version

You can use the plural of a page name without having to create
a page for the plural. This wiki will automatically map
singular and plural version.

For example [camel cases] automatically links to [camel case].

The reverse is true also. The singular automatically links to the 
plural. 

For example: [UseThisWikisAbilityToMakeNaturalLookingLink] 
automatically links to [UseThisWikisAbilityToMakeNaturalLookingLinks]. 

!! A Link Name Can Use Any Text

A link can be formed using any text by specifying the text that
will appear as the link text and the URL that will be followed
if the link is selected. For example, the link 
[some rules for text formatting | TextFormattingRules] is produced
by [[some rules for text formatting | ~TextFormattingRules].
You can even include URLs. For example, the link 
[CA wiki | http:://cawiki.csd.ciena.com] is produced by 
[[CA wiki | http:://cawiki.csd.ciena.com].

This makes it easy to include any link naturally in text.


----
!! Make Common Variations Of Words Point To The Same Page 

The idea is to have only one copy of content for a topic
yet have it accessible via any natural link.

!! Add Links for Abbreviations

Abbreviations are common example of multiple links pointing to the
same content. 

For example, the link [LM] and the link [LineModule] 
both point to the same content. The real link us under 
LM. LineModule uses the [TranscludePlugin] to point to LM.

!! Add Links for Different Wording for the Same Thing

Make different wordings for the same thing point to one place
using the [TranscludePlugin]. This idea is related to
[Use This WikisA bility To Make Natural Looking Links].

For example, the idea of decoupling is used in several different
contexts. In order to provide links that fit naturally in
text, several different ways of saying decoupling were created: 
[decoupling], [decoupled], [decouple], [DecouplingPatterns].


----
!! Do Not Add A Title On Each Page 

Your page name can serve as your page title because
page names are already displayed with spaces.

No other page title is necessary. When making bigger pages out
of smaller pages using the [TranscludePlugin] it makes
the documents flow better by not having a title. The
big document can decide on the title.


-----
!! Use Bullets And Headers For Quick Scanning 

People read wiki for information. Whenever a reader sees a big block
of text they just might keep moving on. There are some techniques
to help structure text so people are more likely to read it.

!! Add Headers

Add paragraph headers using the [exclamation | TextFormattingRules ]
points. Headers allow people to quickly scan a page for the
information they want.


!! Add Bullets

* If a paragraph makes multiple points then organize it using [bullet | TextFormattingRules ] lists. 
* This tells readers immediately how many items there are to pay attention to.

!! Add a Table of Contents Jump Table 

At the top of page create a table of contents with links that
jump to a point in the same page. This currently requires the use of html.
See [Build Environment] for an example.


!! Add Line Breaks to Separate Largish Sections

Use the {{{----}}} line graphic before a heading to separate larger
chunks of text on the same page. Very effective with the [table
of contents jump table].

Consider that you should [Pull Content Out Into Its Own Page].



!! Every Line is a Separate Paragraph

This is a variation of using bullets without the bullets. 

Don't run two or more sentences together in one paragraph.

Instead, separate each sentence into its own paragraph.

This makes it easy for people to read because each paragraph
represents a separate thought.


-----
!! Use Just The Right Amount Of Links

Like Goldilocks there is an amount of linking that is just right.

!! Do Not Link to Every Word or Phrase

This looks so bad on the page it just annoys people so they
won't read the content.

!! Link to the First Use of a Word or Phrase

You don't need to link to every occurrence of a word or phrase.
Linking to the first use of a word or phrase is sufficient.

!! Link to What You Want People to Read

If you don't link to something it is unlikely readers
will take the time to search for it. So link to everything
you want people to read.

-----
!! Pull Content Out Into Its Own Page 

If you see information in a page that can stand on its own then
pull it out and make it have its own page. Then make the original
page link to it or include it.

See [Create Knowledge Nugget Pages With Useful Titles] and
[How To Organize Wiki] for more information.


-----
!! Add Links To Main Page

The main page has a link section for home pages and community topics. Put links to your pages where appropriate so other people can find your topics.