Difference between revisions of "Resources/Wiki contribution"
(Add a section for admonitions) |
m (→Page names vs page titles) |
||
| (9 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{#pagetitle:AtoM wiki style guide}} | {{#pagetitle:AtoM wiki style guide}} | ||
| − | [[Main Page]] > | + | [[Main Page]] > [[Resources]] > '''Resources/Wiki_contribution''' |
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. | 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"> | <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. | + | 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. '''This page is a work in progress!''' More style guide information to come. |
</admonition> | </admonition> | ||
| Line 62: | Line 62: | ||
* Page names are used to create and maintain the desired page hierarchy and permalink - e.g. <code>Development/Accession module/2.x development</code> | * Page names are used to create and maintain the desired page hierarchy and permalink - e.g. <code>Development/Accession module/2.x development</code> | ||
| − | * Page titles are used for display purposes - e.g. "Accession module - 2.x development" | + | * Page titles (display titles) are used for display purposes - e.g. "Accession module - 2.x development" |
* Every page should be given a display title | * Every page should be given a display title | ||
* Every new page name should begin with one of the 5 sections, and proceed accordingly so the page hierarchy is maintained | * Every new page name should begin with one of the 5 sections, and proceed accordingly so the page hierarchy is maintained | ||
| Line 76: | Line 76: | ||
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. | 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. | ||
| − | 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 | + | 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 want it to display as "Community/Events" as you've created it, you can add the following: |
<pre> | <pre> | ||
| Line 103: | Line 103: | ||
Will display as: [[Community/Users|Users]] | Will display as: [[Community/Users|Users]] | ||
</admonition> | </admonition> | ||
| − | |||
| − | |||
==Breadcrumbs== | ==Breadcrumbs== | ||
| Line 112: | Line 110: | ||
* Users should manually add breadcrumbs to new pages, leading back to the [[Main Page]] | * Users should manually add breadcrumbs to new pages, leading back to the [[Main Page]] | ||
* These breadcrumbs should use the page name, NOT the display title | * These breadcrumbs should use the page name, NOT the display title | ||
| − | * Doing so | + | * Doing so exposes the true page title to the user, which might be useful for search, and for understanding the wiki hierarchy |
* Adding the breadcrumb also seems to help with search results being returned | * Adding the breadcrumb also seems to help with search results being returned | ||
* For long breadcrumbs, simplifying the final node to use only the unique part of the page name is acceptable | * For long breadcrumbs, simplifying the final node to use only the unique part of the page name is acceptable | ||
| Line 122: | Line 120: | ||
As discussed in the section above, we are using the true '''page name''' to create clean URLs that maintain the wiki organization and hierarchy, and then adding '''page display titles''' (using <code><nowiki>{{#pagetitle:Title goes here}}</nowiki></code> to add user-friendly page names for display. | As discussed in the section above, we are using the true '''page name''' to create clean URLs that maintain the wiki organization and hierarchy, and then adding '''page display titles''' (using <code><nowiki>{{#pagetitle:Title goes here}}</nowiki></code> to add user-friendly page names for display. | ||
| − | By obfuscating the actual page name however, we may be making it harder for users to find the desired content when searching, or when via recall upon a return visit. | + | By obfuscating the actual page name however, we may be making it harder for users to find the desired content when searching, or when navigating via recall upon a return visit. |
The current version of [https://www.mediawiki.org/wiki/MediaWiki Mediawiki] we are using does add simple breadcrumbs (links back to parent pages in a hierarchy, to assist users with orientation and navigation) automatically - but a) these use the display titles, not the page names, and b) they do not lead all the way back to the [[Main Page]] of the wiki. | The current version of [https://www.mediawiki.org/wiki/MediaWiki Mediawiki] we are using does add simple breadcrumbs (links back to parent pages in a hierarchy, to assist users with orientation and navigation) automatically - but a) these use the display titles, not the page names, and b) they do not lead all the way back to the [[Main Page]] of the wiki. | ||
| Line 191: | Line 189: | ||
----- | ----- | ||
| + | |||
| + | '''Explanation''' | ||
As part of the basic styling of the AtoM wiki, there are 5 admonitions included that can be used when creating a page. These are similar to the admonitions used throughout the AtoM User and Administrator's manuals: | As part of the basic styling of the AtoM wiki, there are 5 admonitions included that can be used when creating a page. These are similar to the admonitions used throughout the AtoM User and Administrator's manuals: | ||
| Line 205: | Line 205: | ||
<admonition type="seealso"> | <admonition type="seealso"> | ||
| − | This is a Seealso admonition. They are used to provide links to related wiki pages or external content. Often they are used in the | + | This is a Seealso admonition. They are used to provide links to related wiki pages or external content. Often they are used in the introductory section of a wiki page (in case the user is not in fact on the page that would help them the most), but they can be used throughout as needed. |
</admonition> | </admonition> | ||
| Line 219: | Line 219: | ||
| − | Admonitions can be added to a page using the following syntax (this example will use the Note admonition | + | Admonitions can be added to a page using the following syntax (this example will use the Note admonition): |
<pre> | <pre> | ||
Latest revision as of 18:26, 6 November 2018
Main Page > Resources > Resources/Wiki_contribution
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. This page is a work in progress! More style guide information to come.
Contents
Categories and page hierarchies
Overview
- Every new page should be added as a child of one of the existing 5 sections
- Every page should be given one of the 5 existing categories at the botttom
- Pages in a sub-section should be listed, or accessible, from the section landing page
- If there are multiple-subsections, those too should act as landing pages listing their children
- Users should be able to click through from the Main page to any lower-level page, regardless of how deep in the hierarchy
Explanation
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.
You can also see how this structure is outlined on the Main Page, in the following diagram:
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 in the page footer 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
Overview
- Page names are used to create and maintain the desired page hierarchy and permalink - e.g.
Development/Accession module/2.x development - Page titles (display titles) are used for display purposes - e.g. "Accession module - 2.x development"
- Every page should be given a display title
- Every new page name should begin with one of the 5 sections, and proceed accordingly so the page hierarchy is maintained
- Page names can be simplified for the sake of a better permalink
- Page display titles in sub-sections should ideally give an indication of the area or section to which they belong
Explanation
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 want 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
Breadcrumbs
Overview
- Users should manually add breadcrumbs to new pages, leading back to the Main Page
- These breadcrumbs should use the page name, NOT the display title
- Doing so exposes the true page title to the user, which might be useful for search, and for understanding the wiki hierarchy
- Adding the breadcrumb also seems to help with search results being returned
- For long breadcrumbs, simplifying the final node to use only the unique part of the page name is acceptable
Explanation
As discussed in the section above, we are using the true page name to create clean URLs that maintain the wiki organization and hierarchy, and then adding page display titles (using {{#pagetitle:Title goes here}} to add user-friendly page names for display.
By obfuscating the actual page name however, we may be making it harder for users to find the desired content when searching, or when navigating via recall upon a return visit.
The current version of Mediawiki we are using does add simple breadcrumbs (links back to parent pages in a hierarchy, to assist users with orientation and navigation) automatically - but a) these use the display titles, not the page names, and b) they do not lead all the way back to the Main Page of the wiki.
Therefore, to aid in search and retrieval, as well as reinforcing the wiki structure for end users, we are manually creating breadcrumbs back to the source pages. This means that the hierarchy of each page is actually stored with page content - so even if MediaWiki changes or the automated breadcrumbs cease to work, our pages still contain contextual information that allows us to understand the intended order and hierarchy of the pages.
In light of this, breadcrumbs created manually should use the full original page name, and not a display title. For example:
{{#pagetitle:Release 2.2}}
[[Main Page]] > [[Releases]] > [[Releases/Release announcements]] > Releases/Release announcements/Release 2.2
In some cases, where the hierarchy is deep, we may cut the full page hierarchy from the final, non-linked breadcrumb. However, even if the display title is different than the final part of the page title, use the original page title. For example, on this page, whose display title is "DCB - MODS template", the breadcrumb is structured like so:
{{#pagetitle:DCB - MODS template}}
[[Main Page]] > [[Development]] > [[Development/Projects]] > [[Development/Projects/DCB]] > [[Development/Projects/DCB/Templates]] > MODS
In this case, the page name was in fact Development/Projects/DCB/Templates/MODS, but in the display, the deep hierarchy meant that the breadcrumb was already running over 2 lines. As such, the final, unlinked "crumb" in the breadcrumb trail used only the unique part of the page name - *not* the page display title.
Overview
- Each page should have a simple footer added
- The footer should include
- Footers can be separated from the main content with a horizontal rule
Explanation
Wikis often tend to be notoriously bad for navigation, perhaps due to how easy it is to create pages, and how much care the user must apply to the content to keep them ordered. Because we are trying to maintain a coherent order for the contents of the AtoM wiki by organizing everything into sections and categories, we hope to also make it easier for users to recognize where they are in the hierarchy, and get back to where they came from without having to rely on the Back button in the browser.
At the top of the page, we've added a breadcrumb trail to help users with orientation and navigation. Ideally, a similar navigational aid should exist at the bottom of the page, as wiki pages can sometimes be quite long. To accommodate this, we have begun adding simple navigational footers to every new page added to the wiki.
These footers are generally separated from the wiki page content by a horizontal rule (e.g. five dashes, ----- or <hr /> in the edit templates), and include links back to the previous page and/or the section's landing page, and a link to the AtoM wiki Main Page.
Additionally, the Category for the page should also be added to the footer.
For example, here is the footer for this page:
------ * [[Resources|Back to Resources]] * [[Main Page|AtoM wiki home]] [[Category:Resources]]
Admonitions
Overview
- The wiki contains 5 different styled admonitions that can be used: note, seealso, tip, important, and warning
- Use the seealso admonition in the introductory section of a page, or as needed in page sections, to link to related content
- Notes are general remarks - informative, but without dire consequences to the user if ignored.
- Use important and warning admonitions when the user must be alerted to the consequences of an action, or inaction.
- Tips are ways of sharing alternate workflows, related ideas for use, etc.
Explanation
As part of the basic styling of the AtoM wiki, there are 5 admonitions included that can be used when creating a page. These are similar to the admonitions used throughout the AtoM User and Administrator's manuals:
Tip
This is a Tip admonition. It is used to pass on helpful advice, alternative workflows or ideas, etc.
Note
This is a Note admonition. It can be used for general remarks - useful information or reference, but without dire consequences if ignored by the user.
Seealso
This is a Seealso admonition. They are used to provide links to related wiki pages or external content. Often they are used in the introductory section of a wiki page (in case the user is not in fact on the page that would help them the most), but they can be used throughout as needed.
Important
This is an Important admonition. It should be used more sparingly, when the user must be alerted about something, such as the consequences of an action, or of inaction.
Warning
This is a Warning admonition. It should also be used sparingly, to alert the user to something, such as the consequences of an action, or of inaction.
Admonitions can be added to a page using the following syntax (this example will use the Note admonition):
<admonition type="note"> content goes here </admonition>
Swap the type="" value for any of the others - note, tip, seealso, important, and warning - as needed. You can also still use wiki styling within an admonition - bullets, images, etc.