Help:Project wiki documentation

From Openitware
Jump to: navigation, search

Contents

Project namespace

A project wiki has its own wiki namespace, named after the project's name. Namespaces for the OpenITWare wiki are created only by the wiki administrators. When a project wiki namespace is created, the project name gets listed in the sidebar in the "projects" box and points to the project's home page in its namespace.

For example, DONATE:Home is the wiki page Home in the OpenITWare namespace called DONATE. All the DONATE wiki pages are created in the namespace DONATE and must be referenced (linked from) a wiki page that resides in the DONATE namespace.

A wiki administrator is responsibility to:

  • Set up the project namespace
  • Create the project home page
  • Add the project link in the "projects" box on the side bar
  • Set the category of the project home page to Project. Include [[Category:Project]] directive at the end of the home page. A link to a category page that lists all the wiki home pages of the projects is created.

If a team of students or individual student needs a wiki for their project, contact the Computing Technology wiki administrator to set it up for you.

Project navigation and searching

Basics

By placing all the project pages in the same namespace, MediaWiki's search features help us find those pages easily. See Finding project pages. DO NOT forget to prefix the name of the any project page with the project's namespace followed by colon, such as DONATE: 2012 Spring System Design Document.

Some projects are developed over several semesters. That is why another hard constraint we impose on the project pages (except for Home and possibly a few more standard pages) is that their names always start with term information. The format is yyyy Term, where yyyy is the year of the semester or term when the project was developed, and Term is mainly Fall, Spring, Summer, or J-Term (other academic terms are possible, though), such as DONATE: 2012 Spring System Design Document.

MediaWiki searching is customized through the use of categories. Again, See Finding project pages. However, to make it more convenient to navigate a project wiki by term or by work product without using the Search box, we implement a simple navigation scheme with a few standard pages.

The navigation scheme uses a web browsing approach because everybody is familiar with it. If the project team has a project documenter who knows how wiki pages can be categorized, then category pages can be used instead.

Web browsing navigation scheme

All project must have a landing page, called Home, such as DONATE:Home. The name of the page is an absolutely strict requirement. That's why the page is set up by the wiki administrator and referenced from the projects sidebar box.

The Home page

  • provides a minimal navigation by itemizing top-level pages
  • briefly describes the project - motivation, objective, challenges, etc

At minimum, a page that ensures by-term navigation is referenced from the Home page and, in turn, must reference Home. An example of how this can be done is shown for an hypothetical project, called Collab (see following section).

Example: Collab project navigation

Home page

  • Is named Collab:Home.
  • Contains the following navigational information at the top of the page, before any section:
    • Home
    • All Terms - a link to the "All Terms" page.
    • More - a link to the "More" page.
  • Has a horizontal line to separate this navigation information from the page sections.
  • Contains sections to provide a high level description of the project.

The wikitext for the navigation scheme on the Collab:Home page is:

*[[Collab:Home | Home]'''
*[[Collab:All Terms| All Terms]]
*[[Collab:More| More]]
----

NOTE: Even though the Home item in the wiki list above has a link, it is not displayed as a link on the Collab:Home page. Instead it is shown in black bold. The exact wikitext can be reused on the All Terms and More pages.

The actual content of the Home page is decided by the project developers. Here there are some suggestions:

  • Motivation section explains why this project is important.
  • Objective section briefly describes what problem the project is trying to solve.
  • Events section features events where the project has been presented, such as the project participation at the UNH Undergraduate Research Conference Poster Session.

All Terms page

  • Is named Collab:All Terms.
  • Contains the following navigational information:
    • Home - a link to the Home page.
    • All Terms
    • More - a link to the wiki page that references the project's work products.
  • Contains a section titled Project Work by Term, which has links for each academic term when a team or individual student worked on the project.

The wikitext for the navigation scheme on the DONATE:All Terms page is identical to the wikitext on the DOANTE:Home and DONATE:More pages.

More page

  • Is named Collab:More.
  • Contains the following navigation information
    • Home - a link to the Home page
    • All Terms - a link to the "All Terms" page
    • More
  • Contains other sections as needed to present and reference the project's work products.

The page has the same wikitext for the navigationscheme as the other pages (Home and All Terms).

Categories

The Home page must have a category tag called "Project". The wiki link:

[[Category:Project]] 

must appear at the very end of the home page.

The other top-level pages that facilitate navigation and have content that is not term dependent, must have a category tag that is the name of the project. For example, "All Terms" or "More" pages in the "Collab" project example have:

[[Category:Collab]]

at the end of the page.

Project additional pages

Project additional pages are created over time during academic terms (fall, spring, summer, J-Term, and so forth) when teams of students or individual students do work on the project as part of a course, independent study, or internship. All project pages must be in the project namespace.

Do NOT forget to use the namespace name, followed by colon, and followed by the page name for every single page of the project!

Page naming

With the exception of the top-level and navigational pages (as exemplified above), the name of any project page must start with the year and term when the page is created and written. For example, Internship2Career:2010 Fall Team Meetings page is a page of the Internship2Career project that was created and written in in 2010 in the Fall semester. Note that the page is in the project namespace, as shown by the Internship2Career: prefix.

Why is date information written in the yyyy Semester format? Read about Page category below first.

Page category

Except for the Home page, any project page must have a category tag that has the name of the project. For example, the 2010 Fall Team Meetings page of the Internship2Career project must have the category:

[[Category:Internship2Career]]

at the very end of the page.

The Browse Categories wiki function can be used to find all pages pertain to a specific project by entering the name of the project. When pages are named using yyy Term format, the listing of found pages is chronological by year.

Page reference

To make sure that any project page is correctly referenced from at least another page, a good practice is to:

  • Choose the page from where you'll reference the new page.
  • In that page, write a reference to the new page. To do so:
    • Enter an interlink to the new page. An example is
[[Internship2Career:2010 Fall Team Meetings|Team Meetings]]

where the first part (before |) is the name of the page (has namespace prefix followed by the page name) and the second part (after |) is the name of the link (or reference).

    • Save your editing.
  • The reference shows up in red. Click on the red link.
  • MediaWiki prompts you that the page does not exist and shows the link you need to click to create the page.

Creating an additional page

It is strongly recommended that you use the method described in the "Page reference" section above. Otherwise, the page has a good chance of remaining "orphan", meaning that there no link to get to it.

Finding all project pages

  • By namespace:
    • Enter special:allpages in the Search box of any wiki page.
    • Select the project name from the namespace pulldown menu.
  • By category:
    • Enter special:categories in the Search box of any wiki page.
    • Click on the category name that correspond to the project of interest.

Documentation life cycle

Project wiki documentation is written each term a team or individual student works on the project.

New project

For a new project

  • A wiki administrator:
    • Creates the project namespace and the Home page in the project namespace.
    • References the project home page from the "projects" box on the sidebar.
  • The project wiki writers are expected to:
    • Read all the guidelines in this article about how additional pages are named, categorized, and linked.
    • Write the project top-level and term-specific pages.

Continuing a project

When a team or student continues work on the project in a new term, new content must be integrated with existing content. At minimum, new term specific pages should be reachable from a page that's referenced in one of the top-level pages.

Example: Collab project "All Terms" page

Assume that the Collab project has the history of four terms: Spring 2011, Fall 2011, Spring 2012, and Summer 2012. Each term has a dedicated page that has links to all the work done in that particular term. We name these pages Collab:2011 Spring, Collab:2011 Fall, and so forth. The top-level "All Terms" has a list of links to all these pages. Here is the wikitext for the "All Terms" page:

* [[Collab:Home | Home]]
* [[Collab:All Terms | All Terms]]
* [[Collab:More | More]]
----
=Project Work by Term=
* [[Collab:2012 Summer | Summer 2012]]
* [[Collab:2012 Spring | Spring 2012]]
* [[Collab:2011 Fall | Fall 2011]]
* [[Collab:2011 Spring | Spring 2011]]

[[Category:Collab]]

OpenITWare examples

  • Each OpenITWare example has its own way of organizing its content over time.
  • Take a look at Speech, DONATE, or Internship2Career, which have been developed for 4 terms (at the time of the last update of this page).

It is fair to say that, as they evolve, the projects have made changes to their organization, in an attempt to simplifying it and keeping it simple.

Maintenance of on-going projects

A project wiki is the collaborative work of many students in the same term and over time. Sometimes, when a page is created the namespace of the project is omitted, or the term information is missing. There is also the case when some pages are moved or deleted. If these pages are referenced from other pages, the references turn "red", meaning that they point to a redirect page or nonexistent page.

Orphan pages

At the beginning of the term, the project wiki documenter has the responsibility of checking for "orphan" project pages that do not have namespace and/or term information in the page name. Reference to these pages must be found, too. This is not a trivial task.

To correct a page name:

  • Move the page to enter a new name that is correct
  • Fix all references to the old page to point now to the new page
  • Ask a wiki administrator to delete the old page.