1. Summary
  2. Files
  3. Support
  4. Report Spam
  5. Create account
  6. Log in

Author Guidelines

From notepad-plus

(Difference between revisions)
Jump to: navigation, search
m (A final note: Typo corrected)
 
(28 intermediate revisions not shown)
Line 1: Line 1:
-
{{New Article}}
+
{{New Article-I| NpWiki++ Author Guidelines}}
 +
 
 +
=== Overview ===
 +
 
 +
Information on the wiki is organised in pages, each of which covers a topic as a regular article. While the breadth of the topic may vary, the page is supposed to remain focused on its topic.
 +
 
 +
A page has both a name and a title. The name is usually short, and is used in forming the URL for the page. It shows in smaller print at the top of the page. Category listings can only report page names.
 +
 
 +
It is recommended for pages to have a title as well. The title explains the topic being covered unambiguously. It displays as a banner headline, which suggests that in most cases it will span across most of the page width. It may happen that the page name, as short and ambiguous as it tends to be, is an adequate enough page title.
=== General rules ===
=== General rules ===
Line 6: Line 14:
* We prefer NP++ as the shortened form of Notepad++.
* We prefer NP++ as the shortened form of Notepad++.
* Titles should be capitalised (that is, all major words should start with capitals)
* Titles should be capitalised (that is, all major words should start with capitals)
-
* Pagenames should be capitalised as well.
+
* Page names should be completely capitalised.
-
* Pagenames may contain spaces and the '+' character
+
* Page names may contain spaces and punctuation. As long as PHP can encode it, it is ok. For this reason, the use of the ampersand ('&') is problematic and better avoided.
 +
* Bots, Vandals, Huns, propagandists, peddlers and other wrongdoers are unwelcome. They will be blocked and/or banned swiftly whoever spots their mischief, reported to Sourceforge, and prosecuted if applicable.
 +
 
 +
=== Editing guidelines ===
 +
 
 +
* "View after saving" is as much encouraged as "Test after shipping". Both practices stand for poor quality and disrespect. Please avoid them. "Errare humanum est, perseverare diabolicum".
 +
* Before and after writing, ask yourself whether you'd like to see inaccurate, off topic, misworded or otherwise inadequate material. The standing assumption is that you don't. Just Show preview and read once more what you wrote before clicking Save page.
 +
* If editing to correct typos, redress a badly formed sentence or such, please do not forget to check the "This is a minor edit" checkbox. This helps figuring out, when viewing the history page, which edits are substantial.
 +
* While filling the Summary field is not mandatory, it is also helpful when reviewing the history of a page. For the sake of all readers, please don't forget it too often. You cannot edit an edit summary after committing it. If you wish to be reminded, you can enable prompting in case of a blank summary, from the Misc. tab in your MediaWiki preference assistant.
 +
* If extensively quoting material that is probably copyrighted, it is advisable to read Sourceforge's [http://alexandria.wiki.sourceforge.net/Terms+of+Use Terms of Use] before proceeding.
 +
* Whenever possible, prefer section editing over whole page editing. This has several minor advantages that add up to making the practice recommended:
 +
** Editing a large page requires the transfer of all its contents. If Sourceforge is not very responsive or there is any kind of network congestion, the benefits of editing only a page section should be obvious. Rendering overhead, while usually small, is also reduced.
 +
** Editing only a section of a page makes [[#Conflict management]] even less likely - see below.
 +
** If anything wrong happens (power outage, markup mangling, ...), editing a section only would confine the damage to the edited section.
 +
** An automatic edit note is generated with the name of the section. While usually this is still too vague, it is better than leaving the summary field blank.
 +
** There is one drawback though: the preview of a section in a table does not show the actual formatting, as part of it is outside the section. You'll need to edit a section containing the whole table to eget a usable preview. But sections inside tables are not that frequent after all.
 +
* If using Firefox / Safari web browsers, there is an add-on called It's All Text that automates the process of transferring edited contents to an editor of your choice (Notepad++ is suggested) and saving changes. Then all sorts of syntax highlighting and proofing techniques can be applied. When using other browsers or plugins, you have to Select all, Copy and Paste, either to transfer contents to an editor or back.
=== New pages ===
=== New pages ===
Line 17: Line 41:
The purpose of this is multiple:
The purpose of this is multiple:
-
* Ensure some homogeneity in page appearance
+
* Ensuring some homogeneity in page appearance
-
* Give a chance to reader to go to another page s s/he landed there by error
+
* Giving readers a chance to go to another page if they landed there in error
-
* Link the page to a specific category used for management
+
* Linking the page to a specific category used for management.
 +
So please don't forget about this header template.
 +
 
 +
=== Conflict management ===
 +
 
 +
At the time of writing, NpWiki++ is still a low traffic place, but this is bound to change as it becomes more popular. As more people will start editing pages, the likelihood of two persons editing a page at the same time will grow from nil to tiny. What to do then?
 +
 
 +
If someone saved the page "behind your back" while you were editing it, NpWiki++ will detect it when you save and present you with a conflict resolution form. It has 5 parts:
 +
# A header of a few lines explaining the situation to you;
 +
# The text that was saved without your being aware of it;
 +
# The diff listing of changes, like you canget on (diff) links on history pages;
 +
# Your text;
 +
# The ordinary footer of edit forms.
 +
 
 +
The next step is to merge your changes into the text in the upper form, because this is what Save page will commit. If you have SCMs (Source Code Management) systems like SVN or Git, you will know the feeling. Wikis in general are places for collaborative display of useful information; this is probably the only applicable guideline here - and one not to depart from.
=== Category links ===
=== Category links ===
They should appear at the bottom of the page, mirrorring their Wiki rendering. This is useful to review the indexing and easily change it.
They should appear at the bottom of the page, mirrorring their Wiki rendering. This is useful to review the indexing and easily change it.
 +
 +
Since there are three levels of clustering and browsing, there should be category links for each of these. The list of known categories can be accessed from the "np++ articles" frame on the sidebar.
 +
 +
A page is expected to belong to one usage class, one or two area and between one and three topics. Depending on the case at hand, these figures can be overrdden.
 +
 +
While usage class and area categories are not expected to grow in number unless on an exceptional basis, the network of topic categories has been thought as much more flexible, and adding to it is encouraged.
Adding a topic/keyword category link is encouraged as soon as it is relevant, and it is to be expected that some people will expect to see the page listed when looking up the keyword.
Adding a topic/keyword category link is encouraged as soon as it is relevant, and it is to be expected that some people will expect to see the page listed when looking up the keyword.
Line 39: Line 83:
While boredom may have been born from uniformity, chaos certainly arises from randomness. Try to integrate into the general look and feel of the Wiki.
While boredom may have been born from uniformity, chaos certainly arises from randomness. Try to integrate into the general look and feel of the Wiki.
-
In order to make source files, menu commands and configuration dialog elements more obvious and standing out from text, specific templates have been designed tospare typing and present the casual reader with an easy to read color code. Authors are encouraged to use all tools in [[Authors Toolbox]], specially in the UI quotes section.
+
In order to make source files, menu commands and configuration dialog elements more obvious and standing out from text, specific templates have been designed tospare typing and present the casual reader with an easy to read color code. Authors are encouraged to use all tools in [[Author Toolbox]], specially in the "UI quotes" section.
-
Editing some pages with advanced formatting mmay prove challenging for people with hardly any expertise in wiki markup. If yu feel you are going to cause a mess, or have already, just ask the admins. We may have enough experience to solve the problem soon.
+
=== A final note ===
 +
Editing some pages with advanced formatting may prove challenging for people with hardly any expertise in wiki markup. If you feel you are going to cause a mess, or already have, just ask the admins. We may have enough experience to solve the problem quick.
[[Category:NpWiki++]]
[[Category:NpWiki++]]

Current revision as of 22:12, 17 September 2011

NpWiki++ Author Guidelines


Contents

Overview

Information on the wiki is organised in pages, each of which covers a topic as a regular article. While the breadth of the topic may vary, the page is supposed to remain focused on its topic.

A page has both a name and a title. The name is usually short, and is used in forming the URL for the page. It shows in smaller print at the top of the page. Category listings can only report page names.

It is recommended for pages to have a title as well. The title explains the topic being covered unambiguously. It displays as a banner headline, which suggests that in most cases it will span across most of the page width. It may happen that the page name, as short and ambiguous as it tends to be, is an adequate enough page title.

General rules

  • Use British English spelling and grammar except where computer terms require US spelling. For example, dialog box, localization, etc.
  • We prefer NP++ as the shortened form of Notepad++.
  • Titles should be capitalised (that is, all major words should start with capitals)
  • Page names should be completely capitalised.
  • Page names may contain spaces and punctuation. As long as PHP can encode it, it is ok. For this reason, the use of the ampersand ('&') is problematic and better avoided.
  • Bots, Vandals, Huns, propagandists, peddlers and other wrongdoers are unwelcome. They will be blocked and/or banned swiftly whoever spots their mischief, reported to Sourceforge, and prosecuted if applicable.

Editing guidelines

  • "View after saving" is as much encouraged as "Test after shipping". Both practices stand for poor quality and disrespect. Please avoid them. "Errare humanum est, perseverare diabolicum".
  • Before and after writing, ask yourself whether you'd like to see inaccurate, off topic, misworded or otherwise inadequate material. The standing assumption is that you don't. Just Show preview and read once more what you wrote before clicking Save page.
  • If editing to correct typos, redress a badly formed sentence or such, please do not forget to check the "This is a minor edit" checkbox. This helps figuring out, when viewing the history page, which edits are substantial.
  • While filling the Summary field is not mandatory, it is also helpful when reviewing the history of a page. For the sake of all readers, please don't forget it too often. You cannot edit an edit summary after committing it. If you wish to be reminded, you can enable prompting in case of a blank summary, from the Misc. tab in your MediaWiki preference assistant.
  • If extensively quoting material that is probably copyrighted, it is advisable to read Sourceforge's Terms of Use before proceeding.
  • Whenever possible, prefer section editing over whole page editing. This has several minor advantages that add up to making the practice recommended:
    • Editing a large page requires the transfer of all its contents. If Sourceforge is not very responsive or there is any kind of network congestion, the benefits of editing only a page section should be obvious. Rendering overhead, while usually small, is also reduced.
    • Editing only a section of a page makes #Conflict management even less likely - see below.
    • If anything wrong happens (power outage, markup mangling, ...), editing a section only would confine the damage to the edited section.
    • An automatic edit note is generated with the name of the section. While usually this is still too vague, it is better than leaving the summary field blank.
    • There is one drawback though: the preview of a section in a table does not show the actual formatting, as part of it is outside the section. You'll need to edit a section containing the whole table to eget a usable preview. But sections inside tables are not that frequent after all.
  • If using Firefox / Safari web browsers, there is an add-on called It's All Text that automates the process of transferring edited contents to an editor of your choice (Notepad++ is suggested) and saving changes. Then all sorts of syntax highlighting and proofing techniques can be applied. When using other browsers or plugins, you have to Select all, Copy and Paste, either to transfer contents to an editor or back.

New pages

New pages should start with either

{{New Article}}

or

{{New Article| Longer and more descriptive header}}

The purpose of this is multiple:

  • Ensuring some homogeneity in page appearance
  • Giving readers a chance to go to another page if they landed there in error
  • Linking the page to a specific category used for management.

So please don't forget about this header template.

Conflict management

At the time of writing, NpWiki++ is still a low traffic place, but this is bound to change as it becomes more popular. As more people will start editing pages, the likelihood of two persons editing a page at the same time will grow from nil to tiny. What to do then?

If someone saved the page "behind your back" while you were editing it, NpWiki++ will detect it when you save and present you with a conflict resolution form. It has 5 parts:

  1. A header of a few lines explaining the situation to you;
  2. The text that was saved without your being aware of it;
  3. The diff listing of changes, like you canget on (diff) links on history pages;
  4. Your text;
  5. The ordinary footer of edit forms.

The next step is to merge your changes into the text in the upper form, because this is what Save page will commit. If you have SCMs (Source Code Management) systems like SVN or Git, you will know the feeling. Wikis in general are places for collaborative display of useful information; this is probably the only applicable guideline here - and one not to depart from.

Category links

They should appear at the bottom of the page, mirrorring their Wiki rendering. This is useful to review the indexing and easily change it.

Since there are three levels of clustering and browsing, there should be category links for each of these. The list of known categories can be accessed from the "np++ articles" frame on the sidebar.

A page is expected to belong to one usage class, one or two area and between one and three topics. Depending on the case at hand, these figures can be overrdden.

While usage class and area categories are not expected to grow in number unless on an exceptional basis, the network of topic categories has been thought as much more flexible, and adding to it is encouraged.

Adding a topic/keyword category link is encouraged as soon as it is relevant, and it is to be expected that some people will expect to see the page listed when looking up the keyword.

Removing a keyword link, however, should be seen as correcting a mistake, or splitting an overloaded topic.

New topics

Adding a category link that didn't exist before is not enough. The category has to be created. You will tell this condition by a red link in the category footer. Simply follow the link. You will be led to editing the new category. Enter

{{kwcat}}

and save page. You are done. What the template does is to generate a presentation text and integrate the new topic into the indexing structure.

Visual codes

While boredom may have been born from uniformity, chaos certainly arises from randomness. Try to integrate into the general look and feel of the Wiki.

In order to make source files, menu commands and configuration dialog elements more obvious and standing out from text, specific templates have been designed tospare typing and present the casual reader with an easy to read color code. Authors are encouraged to use all tools in Author Toolbox, specially in the "UI quotes" section.

A final note

Editing some pages with advanced formatting may prove challenging for people with hardly any expertise in wiki markup. If you feel you are going to cause a mess, or already have, just ask the admins. We may have enough experience to solve the problem quick.

Personal tools
INVISIBLE