Difference between revisions of "Starfleet Commander:Project Help pages"

From Starfleet Commander
Jump to navigationJump to search
m
 
(16 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
'''Project:Help pages,''' is a project to create a set of concise user help pages for the {{ns:Project}} wiki users, i.e. for visitors to this website which is powered by MediaWiki. The project covers all content in the Help namespace. The main entry point for this <s>is</s> <ins>will be</ins> <nowiki>[[Help:Contents]]</nowiki> when finished. As for the project time it is [[Help:Contents/Sandbox]].
 
'''Project:Help pages,''' is a project to create a set of concise user help pages for the {{ns:Project}} wiki users, i.e. for visitors to this website which is powered by MediaWiki. The project covers all content in the Help namespace. The main entry point for this <s>is</s> <ins>will be</ins> <nowiki>[[Help:Contents]]</nowiki> when finished. As for the project time it is [[Help:Contents/Sandbox]].
  
This help documentation is under the Public Domain, and contributors must be clear about the differences in licenses. The help pages do not contain information for server administrators, about how to install, configure, or maintain MediaWiki software. See the 'Goals' below, for a detailed statement of what we are trying to achieve.
+
This help documentation is to be released under the [http://en.wikipedia.org/wiki/Public_Domain Public Domain], and contributors must be clear about the differences in licenses. The help pages do not contain information for server administrators, about how to install, configure, or maintain MediaWiki software. See the 'Goals' below, for a detailed statement of what we are trying to achieve.
  
{{information}}Please '''do not''' copy and paste content from {{meta|Help:Contents|Meta-Wiki's Handbook}} help pages, or from the {{mediawiki|Manual:Contents|MediaWiki Manual}} help pages in here. They were written under the GFDL license and are ''not'' in the public domain.  
+
{{information}}Please '''do not''' copy and paste content from the [http://meta.wikimedia.org/wiki/Help:Contents Meta-Wiki's Handbook], or from the [http://www.mediawiki.org/wiki/Manual:Contents MediaWiki Manual] pages in here. They were written under the GFDL license and are ''not'' in the public domain.  
 
|}
 
|}
  
  
 
__TOC__
 
__TOC__
== Goal ==
+
== Goals ==
 
+
The idea is to provide a set of pages which is adapted to this wiki installation. This will include basic user information and other meta information, in a reasonably concise form. The basic concept is to create a compressed user guide, not a reference work. It should focus on what users want and not explain other functions.
The idea is to provide a set of pages which is adapted to this wiki installation. This will include basic user information and other Meta information, in a reasonably concise form. The basic concept is to create a compressed user guide, not a reference work. It should focus on what users want and not explain other functions.
 
  
 
== License ==
 
== License ==
Contributions to the Help pages are released as '''public domain''' (rather than the usual [[GNU Free Documentation License]]). This is necessary in order to allow people to easily copy the text into their own wiki installations. Please ensure you understand the following before contributing:
+
Contributions to the Help pages are released as '''public domain''' (rather than the usual [http://en.wikipedia.org/wiki/GNU_Free_Documentation_License GNU Free Documentation License]). This is necessary in order to allow people to easily copy the text into their own wiki installations. Please ensure you understand the following before contributing:
  
 
* Every page in the Help namespace must contain the line <code><nowiki>{{PD Help Page}}</nowiki></code> to indicate the license.
 
* Every page in the Help namespace must contain the line <code><nowiki>{{PD Help Page}}</nowiki></code> to indicate the license.
Line 27: Line 26:
  
 
=== ''Not'' server administrators ===
 
=== ''Not'' server administrators ===
We are not aiming to duplicate the full MediaWiki documentation. Information targeted at server administrators, detailing installation, configuration or maintenance of MediaWiki, belongs in the [[Project:Manual|Manual]].  
+
We are not aiming to duplicate the full documentation of the MediaWiki software. Information targeted at server administrators, detailing installation, configuration or maintenance of a MediaWiki installation can be found in the MediaWiki [http://www.mediawiki.org/wiki/Manual:Contents Manual].  
  
The only small exception to this is the 'Admin tips' boxes (described below).
+
There are exceptions to this described in the 'Admin tips' section below.
  
 
=== Information for sysop / bureaucrat users less prominent ===
 
=== Information for sysop / bureaucrat users less prominent ===
The help pages would not be complete, without also describing what 'sysop' users can do, however these more advanced features are not available to majority of a target audience (the majority of wiki users). As such, we should keep this information a little bit separate, so that normal users are not confronted with information which is not relevant to them. Within the bulk of the Help pages we will make brief mentions of things which require sysop privileges, but detailed descriptions of sysop procedures should be tucked away on less prominently linked pages, or should be left out of the Help pages altogether.  
+
The help pages would not be complete, without also describing what 'sysop' users can do, however these more advanced features are not available to majority of a target audience (the majority of wiki users). As such, we should keep this information a little bit separate, so that normal users are not confronted with information which is not relevant to them. Within the bulk of the Help pages we will make brief mentions of things which require sysop privileges, but detailed descriptions of sysop procedures should be tucked away on less prominently linked pages, or should be left out of the Help pages altogether, and instead be provided through external links to the MediaWiki website.
 
 
''This section is [[Project Talk:PD help|under discussion]]''
 
  
 
== Editorial guidelines ==
 
== Editorial guidelines ==
* Create links between the pages, but avoid linking to other namespaces on MediaWiki.org. Keep the links internal to the public domain help pages, or make external links (full URL) to relevant resources e.g. on meta.wikimedia.org. This is to facilitate easier copying of the text into fresh wiki installations.  Do not use interwiki links as these may not exist in the target wiki.
+
* Create links between the pages, but avoid linking to other namespaces on the {{SITENAME}} wiki. Keep the links internal to the public domain help pages, or make external links (full URL) to relevant resources e.g. on meta.wikimedia.org. This is to facilitate easier copying of the text into fresh wiki installations.  Do not use interwiki links as these may not exist in the target wiki.
* We probably don't want to swap in the <nowiki>{{SITENAME}}</nowiki> syntax anywhere. MediaWiki is the name of the software we are describing. This is the software that powers the destination wiki, so anywhere where our text is referring to the software (everywhere throughout help) it should be left as a literal string "MediaWiki". If for some reason the help text is mentioning the name of the site, then this would be an appropriate exception (use <nowiki>{{SITENAME}}</nowiki>), but we are ''not'' going to swap this in everywhere where we mention the word MediaWiki.
+
* We probably don't want to swap in the <nowiki>{{SITENAME}}</nowiki> syntax anywhere. If for some reason the help text is mentioning the name of the site, then this would be an appropriate exception (use <nowiki>{{SITENAME}}</nowiki>), but we are ''not'' going to swap this in everywhere where we mention the word {{SITENAME}}.
 
+
* MediaWiki is the name of the software we are describing. This is the software that powers the destination wiki, so anywhere where our text is referring to the software (everywhere throughout help) it should be left as a literal string "MediaWiki".  
* Translations should be done '''after''' the English version of a page has reached a stable status. The naming convention is <code><nowiki>Pagetitle/language-code</nowiki></code>.
+
* Unless you have the perfect solution for navigation in this manual, please refrain from creating navigation templates and create '''content''' first. However there is one navigation template made for the help pages, [[:Template:Help]].{{Note}}This should be rename "Help list" to be consistent with other navigation lists, like the "Ship List". However there is a current "Helplist" template so this will not be done until the release to public.
 
+
* Do not use extensions since they are not installed on all MediaWiki installations.
* Unless you have the perfect solution for navigation in this manual, please refrain from creating navigation templates and create '''content''' first.
 
 
 
* Do not use extensions such as [[Extension:Cite]], since they are not installed on all MediaWiki installations.
 
  
 
=== Formatting ===
 
=== Formatting ===
* Formatting should be consistent. Use <code><nowiki>{{Prettytable}}</nowiki></code> for any tables you create, highlight cells or rows with <code><nowiki>{{Hl1}}</nowiki></code> etc. (see [[Template talk:Prettytable]])
+
* Formatting should be consistent. Use <code><nowiki>class="wikitable"</nowiki></code> for any tables you create, highlight cells or rows with <code><nowiki>{{Hl1}}</nowiki></code> etc.
  
* All wiki markup and code should be put in <code><nowiki><code></nowiki></code> or <code><nowiki><pre></nowiki></code> tags. Help for inserting: <code><nowiki>{{subst:nw|text}}</nowiki></code>.
+
* All wiki markup and code should be put in <code><nowiki><code></nowiki></code> or <code><nowiki><pre></nowiki></code> tags.
  
 
* All references to menu texts and descriptions should appear in ''italic''.
 
* All references to menu texts and descriptions should appear in ''italic''.
  
=== Screenshot Images ===
+
=== Use of screenshot images ===
 +
A user can choose different skins and therefore the screenshots may not be accurate. So in this implementation of help pages, screenshots are not used. Instead the 'MonoBook' (default skin of this MediaWiki installation) and the popular 'Vector' skin are referred in the text.
  
''There is some discussion about whether we want screenshot images on the help pages. See the [[Project talk:PD help|talk page here]], and also [[Project:Current issues#MW Screenshots - Image license]]''
+
== Admin tips ==
 +
If something in Help can be configured by a server administrator, you can insert an admin tip with <code><nowiki>{{Admin tip|tip=text}}</nowiki></code>.
  
Screenshots are ''deprecated'' until this is decided. i.e. don't add any more, but don't delete the existing ones.
+
{{Information}}The template <tt><nowiki>{{Admin tip}}</nowiki></tt> is not yet implemented.
  
'''Advantages of screenshot images'''
+
== Category ==
* An image says more than words. For friendly user help, it is important to provide illustrations.
+
All pages in the "Help:" namespace is by definition a part of {{ns:Project}} wiki public domain help documentation and should be categorized [[:Category:Help]]. But this "Help pages" project categorizes the pages in the "Help:" namespace with [[:Category:Help pages]] to distinguish them from the current help pages. In keeping with simplicity the pages should be moved to the category "Help" when the project releases to public.
* Some users are visual learners. Images help to include them.
 
* Images help users locate things on the screen.
 
* Images provide feedback by matching what's on the screen with the screenshot.
 
 
 
'''Disadvantages of screenshot images'''
 
* MediaWiki has a built-in import/export feature, but this doesn't work with images.
 
* Licensing issues. Can MediaWiki screenshots be licensed PD?
 
* We can get by without them. Nothing we describe in the help pages ''requires'' an image to illustrate.
 
* Images increase overall file size.
 
* Layout/colour differences between the installation (+selected skin) and the screenshots may be confusing.
 
 
 
== Admin tips ==
 
If something in Help can be configured by a server administrator, you can insert an admin tip with <code><nowiki>{{Admin tip|tip=text}}</nowiki></code>.
 
  
==Category==
+
{{Note}}Most of the pages in the "Help pages" project has the [[:Category:Help]] commented out in the wiki code at the bottom. To move a page simply remove the comment tag, and the template tag <code><nowiki>{{NHP}}</nowiki></code> at the top.
All pages in the "Help:" namespace are by definition part of this wiki's public domain Help documentation project and should be categorized [[:Category:Help]].
 
  
The former category for pages in the "Help:" namespace, this public domain Help documentation project, was [[:Category:Help pages]]. In keeping with simplicity the category is now simply [[:Category:Help]] and all pages <s>have been</s> <ins>should be</ins> updated.
+
== Timeline ==
 +
* Milestone 1 - September 25: Implement help files from PD Help on MediaWiki.org
 +
* Revision 1 - September 30: Adapting the pages to our needs
 +
* Milestone 2 - October 1: Mark for cleanup, copyedit, grammar and spelling check
 +
* Revision 2 - October 15: Release to consensus
 +
* Milestone 3 - October 25: End consensus
 +
* Revision 3 - October 31: Finished implement changes from consensus
 +
* RTP release to public - November 1
  
 
== See also ==
 
== See also ==
 
* '''[[Project:Language policy]]''' if you are interested in working on non-English versions of the help pages.  
 
* '''[[Project:Language policy]]''' if you are interested in working on non-English versions of the help pages.  
  
[[Category:Policy|Project help pages]]
+
[[Category:Wiki Projects|Help pages]]

Latest revision as of 07:48, 14 October 2011

SFC Wiki Draft Icon.png This page is under construction or some major changes are in progress.
Help pages are released without copyrights (public domain)

Project:Help pages, is a project to create a set of concise user help pages for the Starfleet Commander wiki users, i.e. for visitors to this website which is powered by MediaWiki. The project covers all content in the Help namespace. The main entry point for this is will be [[Help:Contents]] when finished. As for the project time it is Help:Contents/Sandbox.

This help documentation is to be released under the Public Domain, and contributors must be clear about the differences in licenses. The help pages do not contain information for server administrators, about how to install, configure, or maintain MediaWiki software. See the 'Goals' below, for a detailed statement of what we are trying to achieve.

i Information:  Please do not copy and paste content from the Meta-Wiki's Handbook, or from the MediaWiki Manual pages in here. They were written under the GFDL license and are not in the public domain.


Goals

The idea is to provide a set of pages which is adapted to this wiki installation. This will include basic user information and other meta information, in a reasonably concise form. The basic concept is to create a compressed user guide, not a reference work. It should focus on what users want and not explain other functions.

License

Contributions to the Help pages are released as public domain (rather than the usual GNU Free Documentation License). This is necessary in order to allow people to easily copy the text into their own wiki installations. Please ensure you understand the following before contributing:

  • Every page in the Help namespace must contain the line {{PD Help Page}} to indicate the license.
  • No content can be copied from elsewhere into these pages, except if you are the author or have permission from the authors. Content that is already public domain can be copied here, but this does NOT include most web pages!
  • You are relinquishing all rights to the information you contribute here. Although you will continue to have your contributions listed and attributed on this site, others can copy the text without giving credit, and can modify it as they see fit.

Target readership - Normal users

The help pages are very much targeted at normal visitors to a wiki website.

Not server administrators

We are not aiming to duplicate the full documentation of the MediaWiki software. Information targeted at server administrators, detailing installation, configuration or maintenance of a MediaWiki installation can be found in the MediaWiki Manual.

There are exceptions to this described in the 'Admin tips' section below.

Information for sysop / bureaucrat users less prominent

The help pages would not be complete, without also describing what 'sysop' users can do, however these more advanced features are not available to majority of a target audience (the majority of wiki users). As such, we should keep this information a little bit separate, so that normal users are not confronted with information which is not relevant to them. Within the bulk of the Help pages we will make brief mentions of things which require sysop privileges, but detailed descriptions of sysop procedures should be tucked away on less prominently linked pages, or should be left out of the Help pages altogether, and instead be provided through external links to the MediaWiki website.

Editorial guidelines

  • Create links between the pages, but avoid linking to other namespaces on the Starfleet Commander wiki. Keep the links internal to the public domain help pages, or make external links (full URL) to relevant resources e.g. on meta.wikimedia.org. This is to facilitate easier copying of the text into fresh wiki installations. Do not use interwiki links as these may not exist in the target wiki.
  • We probably don't want to swap in the {{SITENAME}} syntax anywhere. If for some reason the help text is mentioning the name of the site, then this would be an appropriate exception (use {{SITENAME}}), but we are not going to swap this in everywhere where we mention the word Starfleet Commander.
  • MediaWiki is the name of the software we are describing. This is the software that powers the destination wiki, so anywhere where our text is referring to the software (everywhere throughout help) it should be left as a literal string "MediaWiki".
  • Unless you have the perfect solution for navigation in this manual, please refrain from creating navigation templates and create content first. However there is one navigation template made for the help pages, Template:Help.Light Bulb Icon.png Note: This should be rename "Help list" to be consistent with other navigation lists, like the "Ship List". However there is a current "Helplist" template so this will not be done until the release to public.
  • Do not use extensions since they are not installed on all MediaWiki installations.

Formatting

  • Formatting should be consistent. Use class="wikitable" for any tables you create, highlight cells or rows with {{Hl1}} etc.
  • All wiki markup and code should be put in <code> or <pre> tags.
  • All references to menu texts and descriptions should appear in italic.

Use of screenshot images

A user can choose different skins and therefore the screenshots may not be accurate. So in this implementation of help pages, screenshots are not used. Instead the 'MonoBook' (default skin of this MediaWiki installation) and the popular 'Vector' skin are referred in the text.

Admin tips

If something in Help can be configured by a server administrator, you can insert an admin tip with {{Admin tip|tip=text}}.

i Information:  The template {{Admin tip}} is not yet implemented.

Category

All pages in the "Help:" namespace is by definition a part of Starfleet Commander wiki public domain help documentation and should be categorized Category:Help. But this "Help pages" project categorizes the pages in the "Help:" namespace with Category:Help pages to distinguish them from the current help pages. In keeping with simplicity the pages should be moved to the category "Help" when the project releases to public.

Light Bulb Icon.png Note: Most of the pages in the "Help pages" project has the Category:Help commented out in the wiki code at the bottom. To move a page simply remove the comment tag, and the template tag {{NHP}} at the top.

Timeline

  • Milestone 1 - September 25: Implement help files from PD Help on MediaWiki.org
  • Revision 1 - September 30: Adapting the pages to our needs
  • Milestone 2 - October 1: Mark for cleanup, copyedit, grammar and spelling check
  • Revision 2 - October 15: Release to consensus
  • Milestone 3 - October 25: End consensus
  • Revision 3 - October 31: Finished implement changes from consensus
  • RTP release to public - November 1

See also