Differences between revisions 1 and 16 (spanning 15 versions)
⇤ ← Revision 1 as of 2010-10-15 05:25:40 →
Size: 3531
Editor: mpm
Comment:
← Revision 16 as of 2012-11-06 14:18:50 → ⇥
Size: 5348
Editor: abuehl
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
#pragma section-numbers 2
Line 2: Line 3:
Line 8: Line 8:

The wiki aims to be a moderately coherent body of documentation to supplement the following resources:		 The wiki aims to be a moderately coherent body of useful documentation to supplement the following resources:
Line 17: Line 16:
 * in-depth information and [[CategoryHowto|How-tos]] that are beyond the scope of the book  * in-depth information and [[http://mercurial.selenic.com/wiki/CategoryHowTo|How-tos]] that are beyond the scope of the book
Line 20: Line 19:
 * FAQs, tips, and other useful recipes  * FAQs, tips, quick-starts, and other useful recipes
Line 23: Line 22:
 * documentation of internals   * documentation of internals
Line 28: Line 27:
 * duplication of book and help content
Line 33: Line 33:
Line 39: Line 38:
 * pages that duplicate help or book content
Line 41: Line 41:
 * irrelevant pages courtesy of Moin  * irrelevant pages courtesy of Moin distribution
Line 43: Line 43:
This page describes a collection of janitorial tasks for incrementally improving this situation over time. This page describes a collection of janitorial tasks for incrementally improving this situation over time. Regular wiki users and editors should consider some of these tasks as they visit the wiki.
Line 45: Line 45:
If you have questions, please ask on [[IRC|IRC]]. At some point, as the style and structure plans for the wiki become more firm, we may add all pages to CategoryAudit so that we can mark and sweep everything into the desired structure.
Line 47: Line 47:
If you have questions or suggestions, please ask on [[IRC]].

== Tasks ==
Line 48: Line 51:
Watch the RecentChanges page for the introduction of spam pages and other vandalism. Revert vandalized pages and delete newly-created spam pages and add offending users to BannedGroup (or ask an admin).
Line 49: Line 53:
Watch the RecentChanges page for the introduction of spam pages and other vandalism.
Revert vandalized pages and delete newly-created spam pages and add offending users to BannedUsers (or ask an admin).		 === Mark pages that need style updates ===
We use include pages to mark pages that need particular types of improvement. Add the following to the top of pages that don't match the formatting guidelines:

{{{
<<Include(A:style)>>
}}}
to introduce a style warning and allow such pages to be indexed on CategoryAudit.

The following audit markers currently exist:

<<PageList("A:")>>
Line 53: Line 66:
Consult RecentChanges and PageHits for popular pages to normalize.
Line 54: Line 68:
See the [[WikiStyleGuide|wiki style guide]] for guidelines on page style and edit pages appropriately.
Add pages that need further editing to CategoryAudit.		 See the [[WikiStyleGuide|wiki style guide]] for guidelines on page style and edit pages appropriately. Add appropriate markers to pages so they'll automatically appear in CategoryAudit.
Line 59: Line 72:
=== Relegate old design discussion ===
Pages for feature plans that are no longer relevant (either because they've been implemented or abandoned) should be marked as historic and removed from categories such as CategoryNewFeatures:

{{{
<<Include(A:historic)>>
}}}
Line 60: Line 79:
Line 64: Line 82:
Line 68: Line 85:
There are a number of pages that contain very similar content on the wiki. Also, there are pages (such as command stubs) that ought to be deleted, but contain information that would be appropriate elsewhere on the wiki.
Line 69: Line 87:
There are a number of pages that contain very similar content on the wiki. Use the search tool to find related pages and add them to CategoryProposedMerge.
Include a marker like the following under the title of each page to be merged:

{i} This page's contents should be merged with PageFoo and PageBar.		 Use the search tool to find related pages and add a marker like the following:
Line 75: Line 90:
{i} This page's contents should be merged with PageFoo and PageBar <<Include(A:merge)>>
}}}
If you undertake the consolidating of page contents, remember to redirect the old pages to the new one.

=== Link to built-in help and book topics ===
There are a lot of topics on the wiki that are now covered in help, manpages, and the book. Add links to such content where appropriate. To link to built-in help topics (for instance the [[Topic:revsets|revsets]] topic), use a link like the following:

{{{
[[Topic:revsets|revsets]]
Line 78: Line 101:
If you undertake the consolidating of page contents, remember to redirect the old pages to the new one. For the [[Cmd:branch|hg branch]] command, use a link like this:

{{{
[[Cmd:branch|hg branch]]
}}}

The InterWikiMap page has a list of link shortcuts for things like commands, topics, issues, and so on. You can use these instead of entering the full URL for a resource.

For pages whose contents are completely covered by these resources, see the section below on page deletion.
Line 81: Line 112:

Add pages that don't seem appropriate for the wiki (irrelevant stubs, random commentary, etc.) to CategoryProposedDeletion and include a marker like the following under the title:

/!\ This page is proposed for deletion.		 Mark pages that don't seem appropriate for the wiki (irrelevant stubs, random commentary, etc.) for deletion by include a marker like the above the title:
Line 87: Line 115:
/!\ This page is proposed for deletion. <<Include(A:delete)>>
Line 93: Line 121:
Line 97: Line 124:

Visit CategoryStubs and WantedPages and expand wiki content. 		 Visit CategoryStubs and WantedPages and expand wiki content.

Wiki Cleanup

This describes plans for improving the Mercurial wiki.

Contents

  1. Goal
  2. Improvement plan
  3. Tasks
    1. Spam removal
    2. Mark pages that need style updates
    3. Update pages and page names to match wiki style
    4. Relegate old design discussion
    5. Remove discussion
    6. Fix orphaned and abandoned pages
    7. Mark pages needing merging
    8. Link to built-in help and book topics
    9. Page deletion
    10. Fix broken links
    11. Expand stubs and create needed pages

1. Goal

The wiki aims to be a moderately coherent body of useful documentation to supplement the following resources:

As such, it makes sense to have things like the following:

  • in-depth information and How-tos that are beyond the scope of the book

  • information about extensions and third-party tools
  • links to other resources
  • FAQs, tips, quick-starts, and other useful recipes
  • best practices
  • migration and conversion assistance
  • documentation of internals
  • development plans and other information for contributors

Things that probably don't make sense for the wiki include:

  • duplication of book and help content
  • discussion - use the mailing lists
  • non-best practices
  • advertising

2. Improvement plan

As of October 2010, much of the wiki suffers from:

  • inconsistent formatting and style
  • poor linking and organization
  • excessive duplication
  • pages that duplicate help or book content
  • lots of stub pages
  • random commentary and non-canonical advice
  • irrelevant pages courtesy of Moin distribution

This page describes a collection of janitorial tasks for incrementally improving this situation over time. Regular wiki users and editors should consider some of these tasks as they visit the wiki.

At some point, as the style and structure plans for the wiki become more firm, we may add all pages to CategoryAudit so that we can mark and sweep everything into the desired structure.

If you have questions or suggestions, please ask on IRC.

3. Tasks

3.1. Spam removal

Watch the RecentChanges page for the introduction of spam pages and other vandalism. Revert vandalized pages and delete newly-created spam pages and add offending users to BannedGroup (or ask an admin).

3.2. Mark pages that need style updates

We use include pages to mark pages that need particular types of improvement. Add the following to the top of pages that don't match the formatting guidelines: 

<<Include(A:style)>>

to introduce a style warning and allow such pages to be indexed on CategoryAudit.

The following audit markers currently exist:

  1. A:dated
  2. A:delete
  3. A:dev
  4. A:historic
  5. A:merge
  6. A:stub
  7. A:style

3.3. Update pages and page names to match wiki style

Consult RecentChanges and PageHits for popular pages to normalize.

See the wiki style guide for guidelines on page style and edit pages appropriately. Add appropriate markers to pages so they'll automatically appear in CategoryAudit.

Add redirects to renamed pages to avoid breaking existing links.

3.4. Relegate old design discussion

Pages for feature plans that are no longer relevant (either because they've been implemented or abandoned) should be marked as historic and removed from categories such as CategoryNewFeatures: 

<<Include(A:historic)>>

3.5. Remove discussion

Some pages have discussion questions that belong elsewhere. Either move these to a '/Talk' subpage or delete them.

3.6. Fix orphaned and abandoned pages

Visit OrphanedPages and AbandonedPages to find pages that need attention and add appropriate categories and links from other pages.

3.7. Mark pages needing merging

There are a number of pages that contain very similar content on the wiki. Also, there are pages (such as command stubs) that ought to be deleted, but contain information that would be appropriate elsewhere on the wiki.

Use the search tool to find related pages and add a marker like the following: 

<<Include(A:merge)>>

If you undertake the consolidating of page contents, remember to redirect the old pages to the new one.

There are a lot of topics on the wiki that are now covered in help, manpages, and the book. Add links to such content where appropriate. To link to built-in help topics (for instance the revsets topic), use a link like the following: 

[[Topic:revsets|revsets]]

For the hg branch command, use a link like this: 

[[Cmd:branch|hg branch]]

The InterWikiMap page has a list of link shortcuts for things like commands, topics, issues, and so on. You can use these instead of entering the full URL for a resource.

For pages whose contents are completely covered by these resources, see the section below on page deletion.

3.9. Page deletion

Mark pages that don't seem appropriate for the wiki (irrelevant stubs, random commentary, etc.) for deletion by include a marker like the above the title: 

<<Include(A:delete)>>

Use the 'Local Site Map' action to find pages that link to a page and remove those links.

Visit WantedPages and point broken links to appropriate pages or remove them as appropriate.

3.11. Expand stubs and create needed pages

Visit CategoryStubs and WantedPages and expand wiki content.

CategoryWiki

WikiCleanup (last edited 2013-09-01 01:19:02 by KevinBot)