Codex Reorganization
The reorganization of the Gallery wiki / codex has been discussed many times in IRC and in the Gallery mailing-lists. This article provides an overview of the aspects that have been agreed on, some alternatives and the open questions.
Goals
- Make information easier to find
- Set a good structure as a base for easier maintenance and to simplify the life of contributors
The following measures should help to achieve the above high-level goals:
- Restructure the front-page of codex.galleryproject.org
- Define top-level categories
- Define what links should be on the frontpage (mostly top-level categories) and how the page should be structured.
- Define a categorization that covers all Gallery matters
- Categorize existing content into the new categories
- Use templates as far as possible and use color to differentiate major categories / areas.
- Landing pages are needed for complex / high-profile categories, e.g. for Development
The new structure of the front-page is mostly based on the top categeories resulting from the new categorization.
TODO
- A poll for the suggested front-page links (could be done during next Gallery meeting)
- Agree on top-level categories (prepare list of top-level categories and discuss / vote in Gallery meeting)
- Decide whether we want namespaces or not
- Get zimzat to create demo of templates
- Categorize existing content in new categories
- Fine-tune / Categorize in sub-categories
Data and Statistics
The new categorization should be based on existing usage patterns and data that shows what users are expecting to find in what location.
Card Sorting Exercise
Valerie Riedel, a professional information architect, conducted a card-sorting exercise with users of Gallery which would become the most important data points to base the new codex categorization on.
The results of the survey can be found at:
Usage Statistics
Main Page
Main Page categories (h0bbel, -docs, 2006/07/17
Gallery 1
Quick Start Guide
Introduction / About
Installation
Administration & Maintenance
Usage
Troubleshooting
FAQ
Gallery 2
Quick Start Guide
Introduction / About
Installation
Administration & Maintenance
Usage
Troubleshooting
FAQ
Other Gallery Projects
Gallery Remote
GLoSS
More Projects
Gallery
Develop for Gallery
Downloads
About the Gallery Project
Codex
GMC
Notes:
- Although "Installation" and other help sub-categories are not a top-category, it would be linked from the front-page.
- "Quick start guide" was removed from the frontpage. It shouldn't be a category of itself
- Considering that a lot of card sorters expect a "Getting Started", should we really drop it? --Valiant 07:52, 28 November 2006 (PST)
- The attendees of the docs meeting agreed on adding "Quick Start Guide" --Valiant 15:57, 7 December 2006 (PST)
- There's a general agreement that we don't need to repeat the word "Gallery" everywhere, especially not on the frontpage
- Try to use a "Help" label in some friendly way on the main page, as the card sorting indicated that "Help" is good.
Comments:
- I would rename "(Other/More) Clients" to "More". Reasoning: The category is "Other Gallery Projects" --Valiant 07:52, 28 November 2006 (PST)
- I went forward and changed this --Valiant 15:57, 7 December 2006 (PST)
- I'd drop "Gallery Local" from the frontpage. See recent -core emails. We changed the current frontpage appropriately already. --Valiant 07:52, 28 November 2006 (PST)
- Updated. We might need to consider "Quick Start Guide" for GR too IMO --Valiant 15:57, 7 December 2006 (PST)
- Embedding & Integration would be highly cross-linked, especially from the several top-categories / landing pages. --Valiant 07:52, 28 November 2006 (PST)
Launch Checklist
-
Replace contents of Downloads with Sandbox:Downloads
-
Check Sandbox:Downloads for any pages that link there (including the one on Sandbox:Main_Page)
-
Create Development page with contents from Sandbox:Development_Main_Page
-
Check Sandbox:Development_Main_Page for any pages that link there (including the one on Sandbox:Main_Page)
-
Replace contents of Main_Page with Sandbox:Main_Page
-
Check Sandbox:Main_Page for any pages that link there
- Change GMC Support link to point to Category:Gallery_2:Troubleshooting#Asking_for_Help
-
Change GMC development link to point to Development page on codex
-
Change GMC downloads link to point to Downloads page on codex
- Change Support Forum topic templates to point to new pages
-
Change GMC "Latest Releases" link (in downloadblock) to point to new Downloads page: done for g1/gr
- Change GMC 'about' link to Gallery:About from codex
- Change GMC 'features' link to 'evaluate Gallery / try the demo'
- Replace content of GMC's feature page with links to Gallery1:Features, Gallery2:About and Evaluate_Gallery
New Categorization
Based on the card-sorting exercise Valerie recommends:
- Use nouns for category names (e.g. Installation, Customization)
- Consider re-titling content pages to use a task-focus (e.g. installing, customizing)
- Consider cross-linking more often (e.g. Download link on Getting Started page)
Suggested Process to create the new categorization:
- Agree on the top-level categories, keeping an eye on p. 5 through 7 of the summary report I sent out. These pages show what % of users supported a specific category label. Check the cluster tree file I sent as well to look at users' natural groupings of content. The groupings may suggest additional categories that you will want to create, or suggest a need for subcategories.
- If you create a new category/subcategory, check against p. 5 through 7 to zero in on the best possible name for the new cat/subcat.
- Decide which existing webpages belong in which categories, based on your familiarity with the pages' content, and the groupings shown in the cluster tree.
- Assess whether there are better titles for the pages in question. On page 2 of the summary report (the table), locate each page in the right column, and in the left column of the table see which original card name corresponded to it. If you like the card name better, rename the page. You can also work on this by using the info. on page 5 through 7 to see which category labels received greatest agreement among users.
Conventions:
- Put category information below page content
- Use Space in category names for Gallery #, e.g, "Gallery 2:Help"
- Use "Gallery #:Development:Themes/Embedded/Modules" categories
Open discussions:
- Use "Gallery 2:Help:Installation" or flat "Gallery 2:Installation" ?
- "Gallery 2:Help:Installation" preferred since it gives us a Help category page with the Installation subcategory on it
- thumb asks: Is it possible to tag a single page with multiple categories? By this, I'm wondering if it's possible to provide multiple paths to the same content? If so, how does one apply the categories and create links? Is it possible to have the following examples point to the same content? "Gallery 2:Configuration:Image Size Settings" and "Gallery 2:How to:Change Image Size Settings"
Mockups & Prototypes
-
Sandbox:Developer_Main_Page|Developer Main Page proposed by zimzat
- New Categorization proposed by mindless
- Frontpage suggested by zimzat:
Gallery # (repeat for each Gallery #, or make a new menu for each one)
Introduction / About
Quick Start Guide
Download
Installation
Configuration /(and/or)/ Customization
Usage
FAQ
Troubleshooting
Other Gallery Projects
Gallery Remote
Gallery Local
(Other/More) Clients
- Examples from other projects:
Templates
Naming
- Put the categories into the template such that category-name changes are handled centrally (input from zimzat, recommendation from mediawiki docs)
- Are template-names based on category names? What if the category name changes?
- We could g1 or g2 prefix for template names. We could also reuse templates for both G1 and G2 by adding a parameter that is automatically converted into the full Gallery 1 and Gallery 2 postfix string.
- zimzat writes: "I think the best thing to base the name on is the category name itself"
- suggests: Why not use neutral identifiers for the templates and have a single table on a page as an index that maps identifiers to a description of the template. If the category changes, we can just change the description on that look-up table. The table would probably only be used by page-authors that are in search for an appropriate template. --Valiant 07:52, 28 November 2006 (PST)
- I can't guarantee these templates will work without some minor tweaks, but this is the general idea. They also require the http://meta.wikimedia.org/wiki/ParserFunctions extension.
Code
Template:Category (minus all the new lines) <includeonly>
[[Category:
{{ #ifeq: {{{V| }}}| ||Gallery {{{V}}}:}} {{{1}}}
|
{{ #if: {{{KEY|}}}|{{{KEY}}}|{{PAGENAME}}}}
]]
</includeonly>
Template:C:Installation (minus all the new lines) <includeonly> {{Category|Installation|KEY={{{KEY|}}}|V={{{V|}}}}}
</includeonly>
Page:
{{C:Installation}}
or
{{C:Installation|V=1}}
or
{{C:Installation|KEY=sort order}}
or
{{C:Installation|V=1|KEY=sort order}}
Here is a version of the templates that doesn't require the parser functions extension. It's not as elegant, but it should work (Disclaimer: with minor tweaks).
Template:Category (minus any new lines)
<includeonly>[[Category:{{{V}}}{{{1}}}|{{{KEY|{{PAGENAME}}}}]]</includeonly>
Template:C:Installation (minus any new lines) <includeonly>{{Category|Installation|V=Gallery
{{{V|}}}:|KEY={{{KEY|}}}}}</includeonly>
Page
{{C:Installation|V=2|KEY=sort order}}
Actually, these might be better for now.
PS: The reason for the three tier system (Page -> Intermediate -> Category) is so that any information you want displayed on each page in a category can be added to Template:C:Installation (etc) while reusing the category name and making it easy to edit as needed.
Namespaces
All of the wiki entries that have Gallery2: and Gallery1: Aren't actually in their own namespace.
The "Note: Any existing pages whose titles start with the letters "Foo:" or "Foo talk:" will become unavailable,
so you'd better rename them first." Section bothered me a bit.
Why do we need namespaces, doesn't proper categorization help us achive what we want? Also, should be create
"Landing Pages" for each top level category?
E.g one for Gallery 1, one for Gallery 2 and so on? I think it makes sense to do so.
- Namespaces: G1, G2, GR, ..., several integrations. It could be worth it. --Valiant 07:52, 28 November 2006 (PST)
Open Discussion:
- Do we actually need namespaces?
Landing Pages
-
e.g. a the "Development" link on GMC should point to a landing page (see zimzat's mockup for the Sandbox:Developer_Main_Page|Developer Main Page)
- Have a manually created landing page where it's needed, but generally use automatically generated ones (category pages)
How to organize content
- Organize by Index of How-To docs?
- We have some prefixed content like Gallery2:Module:rewrite, Gallery2:FAQ, ... should we consider all other content as yet to be categorized?
- Should we put all docs / small snippets into codex pages or is it ok if some Tutorials / howto's are just links to certain forum posts?
Categorization for Existing Content
- There are certainly areas where G1/G2 separation makes sense, but I'm not sure a full copy of all subcategories in each is the way to go. For example "About Gallery" set of documents probably should cover both products, as someone coming in to learn about gallery shouldn't have to pick G1/G2 right away... and where would we categorize the G1/G2 comparison? I guess I'd put that doc, requirements and features docs for both G1/G2 all into a single "About Gallery" category.
- "Getting Started With .." or "Quick Start Guide"
For G2 at least, this is currently in README.html included with the product. Not sure what content from codex would go in these.
- "Installation" - maybe group Upgrade info in here too?
- "Customization" - listed under each Gx, then separate category below for "Develop for Gallery".. I guess we have to decide where to draw the line for developer info vs user info. Despite the fact that many "customizers" aren't really "developers" it is more clear cut to define developer info as anything that involves editing files.. so even html changes in tpl files would count here.
This would put all customization info into developer docs, unless we have some docs about how to edit theme and module settings...
- "Help" - we have some "Troubleshooting" info (mostly in the FAQ, also Known Issues) and quite a bit of "How To" info.. would all these go under Help?
- The Usability stuff probably deserves its own subcategory under Project info.
- +1 for "How to" category, maybe "How to:Gallery #:Subject/Category"
- How about a "Gallery #:Configuration:" category? Was this suggested?
- Was an "Installation" category discussed?
Maintenance
Copied from an email by zimzat from May 15th, 2006:
Schedule & Measures
We need to import the templates related to wiki maintenance and upkeep.
The ones I have in mind are the templates asking for an article to be
deleted, split, merged, etc as well as the ones about codify, wikify,
etc an article. This gives a way for the community as a whole to keep
track of what needs done as well as notify moderators and admins of what
they need to do (i.e., delete a spam article in case it slips under the
radar).
The documentation team needs to meet at least once a month to survey
what needs done. It wouldn't be far fetched to meet twice a month (or
once a week). During the meeting current tasks need discussed and
assigned as warranted. If a list of tasks that need done is kept up by
the team then meetings would only need to happen if things got backed up
again.
Special Pages
These are Special pages in the MediaWiki software that help people find
trouble pages. Trouble pages are ones that need editing, deleted, added,
moved, etc. They are also things that only people closely familiar with
the Codex can really do much about, although there are some exceptions
in the list.
Ancient Pages
Special:Ancientpages
- Pages sorted by last modified from oldest to newest.
- Pages that haven't been modified in a long time might be outdated or,
- worst yet, unlinked so no one knows they exist and need updating (that
will be covered later as well).
Recommendation: Reviewing the list of Ancient Pages from time to time,
once or twice a month, should help keep things up to date.
Double redirects
Special:DoubleRedirects
- Redirects that redirect to a redirect.
- When a page redirects to a page that also redirects it stops
redirecting to keep infinite redirects from occurring.
- Pages that are listed here either need redirected to the end page, deleted, or fixed in some other manner.
Recommendation: Change pages that link to the first redirect to the end
redirect, and then redirect all intermediate redirects to the final page as well.
Long pages
Special:Longpages
- Pages sorted by byte size from largest to smallest.
- Pages that are too big make it hard to find information quickly and,
- more than likely, cover too many topics. They can also be hard to
quickly edit minor typos.
Recommendation: Pages that more than 16KB, 32KB, or some other
pre-decided length (32KB should be sufficient) should be looked into for
splitting into multiple pages or alternative organizing (e.g.
Gallery2:PHP Version could have all the whitespace removed from the
function lists),
Orphaned pages
Special:Lonelypages
- These pages aren't linked to anywhere.
- Some pages don't need to be linked anywhere (e.g. Sandbox:Experimental); however, for most pages it is death to be
Orphaned. There is no way for anyone to discover these pages from the
main page or anywhere else unless they do a search for them.
Recommendation: Find a related page to link to pages on this list from.
Even pages that are only vaguely related will do so long as these pages
get some exposure. If another page needs to be created to link to
another page, request it somewhere.
Uncategorized pages and categories
Special:Uncategorizedpages, Special:Uncategorizedcategories
- Pages and categories that aren't in any categories (uncategorized).
- These pages list all of the categories and pages that don't currently
belong to a category. Properly categorized pages and categories allow
users to do a guided search through the Codex to find information
relevant to what they're looking for. For example, someone looking for
modules for Gallery 2 could go to the Gallery 2 category, then the
Modules subcategory, and from there view a list of all the modules in
the Codex for which they can get more information about.
Recommendation: All pages should belong to at least one category, and
all categories (except two or three root categories) should be a
subcategory of another category.
Wanted Pages
Special:Wantedpages
- Pages that do not exist linked to from existing pages.
- Pages on this list may be requested pages that need added or another
page might have a misspelled link.
Recommendation: Add requested pages or correct links on pages that link
to non-existent pages as needed.
