Difference between revisions of "Resources/Wiki contribution"
(Move TODO contents from homepage to Unification page) |
(Add initial content to change page into a style guide) |
||
| Line 1: | Line 1: | ||
| − | # | + | {{#pagetitle:AtoM wiki style guide}} |
| − | + | [[Main Page]] > Unification | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | ---- | + | This page is a style guide for community users and Artefactual staff who intend to contribute content to the Access to Memory wiki. In 2015, we began a project of consolidation and reorganization, moving content from several different out-of-date wikis (Qubit-Toolkit, DCB, Artefactual Wiki, ICA-AtoM wiki), reorganizing it to make it more accessible, and updating it so it was still relevant to the project. We hope to keep this new wiki well organized with a consistent hierarchical structure to the pages, to make end user navigation much easier. The following guide will offer tips and suggestions on how to create pages for the wiki, in line with how other pages have been migrated thus far. |
| − | = | + | <admonition type="tip"> |
| − | + | This page has also been created following the recommendations found in this style guide. You can look at the raw text of the page to see how we've created it if you'd like an example. | |
| − | + | </admonition> | |
| − | + | ==Categories and page hierarchies== | |
| − | < | + | This wiki has been organized into 5 main sections - each section has been given a landing page. These sections are: |
| − | + | ||
| − | </ | + | * [[Community]] |
| + | * [[Development]] | ||
| + | * [[FAQ]] | ||
| + | * [[Releases]] | ||
| + | * [[Resources]] | ||
| + | |||
| + | |||
| + | Each of these landing pages should give the user a sense of what they will find - a brief description of what the section comprises should be included at the top. If there are further subsections in the hierarchy, then the page should be broken up into sections with the title of the section acting as a link, and including a brief description of what the user can expect to find in each subsection below. | ||
| + | |||
| + | <admonition type="tip"> | ||
| + | See the [[Releases]] page for a good, simple example of this practice. | ||
| + | </admonition> | ||
| + | |||
| + | <admonition type="important"> | ||
| + | Make sure that if you create sub-pages in a section, you list them somehow on the landing page above in the hierarchy. Users should be able to click through to any page from the main page, no matter how deep in the hierarchy of a section - they should not have to search for a page to find it if they know what section it should be in. | ||
| + | </admonition> | ||
| + | |||
| + | The wiki has also been given 5 corresponding categories: | ||
| + | |||
| + | * [[:Category:Community]] | ||
| + | * [[:Category:Development documentation]] | ||
| + | * [[:Category:FAQ]] | ||
| + | * [[:Category:Releases]] | ||
| + | * [[:Category:Resources]] | ||
| − | |||
| − | + | '''Every page should be tagged at the bottom with a corresponding category.''' This is important so that the category can act as an index for all pages in a section. This also allows us to review the organization and see if we have forgotten to list a sub-page on its corresponding section landing page. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | ==Page names vs page titles== | |
| − | + | With Mediawiki (the kind of wiki we're using), the only way to create a proper hierarchy is to name the page the way you want the URL to look. So: Let's say you've created the page [[Community]], and now you want to create a sub-page, Community events. | |
| − | + | To nest this new page properly under the [[Community]] page, you will need to create a new page entitled <code>Community/Events</code>. You could name it <code>Community/Community_events</code>, but in terms of the permalink URL for the page, that would be redundant - the page is already in the Community section. This page name, used to maintain the hierarchy, is different from the display page title you can give the page after. | |
| − | So | + | Once you have created your page, you can now add a title, by adding a line of code at the top of the edit page, demonstrated below. So, if you want to name your page "Community events," and you don't wan it to display as "Community/Events" as you've created it, you can add the following: |
<pre> | <pre> | ||
| − | + | {{#pagetitle: Community events }} | |
</pre> | </pre> | ||
| − | + | Every page should have a display title, and the actual page name should be constructed consistently depending on the section hierarchy. The page name should be economical, avoiding repetition - think of it as your chance to create a simple URL, more than a page name. The page title is where you handle the display. | |
| + | |||
| + | So for example - let's say you wanted to organize your new Community events page into sub-sections, first by year, then by month. That would mean that to create a new landing page for events taking place in October of 2015, the '''page name''' might be: | ||
| + | |||
| + | <pre> | ||
| + | Community/Events/2015/10 | ||
| + | </pre> | ||
| + | but the page title added to this page might be: | ||
<pre> | <pre> | ||
| − | + | {{#pagetitle:Community events - October 2015}} | |
</pre> | </pre> | ||
| − | = | + | <admonition type="tip"> |
| + | You can also give links to pages that same clean display title look, like this: | ||
| + | <pre> | ||
| + | [[Community/Users|Users]] | ||
| + | </pre> | ||
| − | + | Will display as: [[Community/Users|Users]] | |
| − | + | </admonition> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | '''SUGGESTION''': | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | I've noted that changing the page title display does not actually change the page name - so searching for "Users" will not bring up a result in the autocomplete for search (only searching for Community/Users will). | |
| − | + | My suggestion, to at least try to make this more clear, is to keep the original page name in the breadcrumb - i.e. since the page you are on is not actually entered as a hyperlink when manually creating the breadcrumb, we might as well leave it as the full page name. | |
| − | |||
| − | |||
| − | + | So.... NOT LIKE THIS: | |
| − | + | <pre> | |
| − | + | [[Main Page]] > [[Community]] > Users | |
| − | + | </pre> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | BUT LIKE THIS: | |
| − | + | <pre> | |
| − | + | [[Main Page]] > [[Community]] > Community/Users | |
| − | + | </pre> | |
| − | |||
| − | |||
| − | + | ----- | |
| − | * | + | * [[Resources|Back to Resources]] |
| − | + | * [[Main Page|AtoM wiki home]] | |
| − | * | ||
| − | |||
| − | + | [[Category:Resources]] | |
| − | |||
| − | |||
| − | |||
Revision as of 18:03, 7 August 2015
Main Page > Unification
This page is a style guide for community users and Artefactual staff who intend to contribute content to the Access to Memory wiki. In 2015, we began a project of consolidation and reorganization, moving content from several different out-of-date wikis (Qubit-Toolkit, DCB, Artefactual Wiki, ICA-AtoM wiki), reorganizing it to make it more accessible, and updating it so it was still relevant to the project. We hope to keep this new wiki well organized with a consistent hierarchical structure to the pages, to make end user navigation much easier. The following guide will offer tips and suggestions on how to create pages for the wiki, in line with how other pages have been migrated thus far.
Tip
This page has also been created following the recommendations found in this style guide. You can look at the raw text of the page to see how we've created it if you'd like an example.
Categories and page hierarchies
This wiki has been organized into 5 main sections - each section has been given a landing page. These sections are:
Each of these landing pages should give the user a sense of what they will find - a brief description of what the section comprises should be included at the top. If there are further subsections in the hierarchy, then the page should be broken up into sections with the title of the section acting as a link, and including a brief description of what the user can expect to find in each subsection below.
Important
Make sure that if you create sub-pages in a section, you list them somehow on the landing page above in the hierarchy. Users should be able to click through to any page from the main page, no matter how deep in the hierarchy of a section - they should not have to search for a page to find it if they know what section it should be in.
The wiki has also been given 5 corresponding categories:
- Category:Community
- Category:Development documentation
- Category:FAQ
- Category:Releases
- Category:Resources
Every page should be tagged at the bottom with a corresponding category. This is important so that the category can act as an index for all pages in a section. This also allows us to review the organization and see if we have forgotten to list a sub-page on its corresponding section landing page.
Page names vs page titles
With Mediawiki (the kind of wiki we're using), the only way to create a proper hierarchy is to name the page the way you want the URL to look. So: Let's say you've created the page Community, and now you want to create a sub-page, Community events.
To nest this new page properly under the Community page, you will need to create a new page entitled Community/Events. You could name it Community/Community_events, but in terms of the permalink URL for the page, that would be redundant - the page is already in the Community section. This page name, used to maintain the hierarchy, is different from the display page title you can give the page after.
Once you have created your page, you can now add a title, by adding a line of code at the top of the edit page, demonstrated below. So, if you want to name your page "Community events," and you don't wan it to display as "Community/Events" as you've created it, you can add the following:
{{#pagetitle: Community events }}
Every page should have a display title, and the actual page name should be constructed consistently depending on the section hierarchy. The page name should be economical, avoiding repetition - think of it as your chance to create a simple URL, more than a page name. The page title is where you handle the display.
So for example - let's say you wanted to organize your new Community events page into sub-sections, first by year, then by month. That would mean that to create a new landing page for events taking place in October of 2015, the page name might be:
Community/Events/2015/10
but the page title added to this page might be:
{{#pagetitle:Community events - October 2015}}
Tip
You can also give links to pages that same clean display title look, like this:
[[Community/Users|Users]]
Will display as: Users
SUGGESTION:
I've noted that changing the page title display does not actually change the page name - so searching for "Users" will not bring up a result in the autocomplete for search (only searching for Community/Users will).
My suggestion, to at least try to make this more clear, is to keep the original page name in the breadcrumb - i.e. since the page you are on is not actually entered as a hyperlink when manually creating the breadcrumb, we might as well leave it as the full page name.
So.... NOT LIKE THIS:
[[Main Page]] > [[Community]] > Users
BUT LIKE THIS:
[[Main Page]] > [[Community]] > Community/Users