This is version . It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

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.

Naming Conventions#

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 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 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 inforamation.

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.

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.

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 is produced by [some rules for text formatting | TextFormattingRules]. You can even include URLs. For example, the link CA wiki is produced by [CA wiki | http:://].

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

Add new attachment

Only authorized users are allowed to upload new attachments.
« This particular version was published on 12-Nov-2003 01:35 by