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

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.

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

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.

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-12) was last changed on 16-Mar-2011 21:28 by Janne Jalkanen