Help:Editing

From NeoWiki

(Difference between revisions)
Jump to: navigation, search
Revision as of 06:40, 9 January 2007 (edit)
Sardisson (Talk | contribs)
m (/* Mac vs. Windows- nix - botlangbar)
← Previous diff
Current revision (20:14, 6 December 2015) (edit) (undo)
Sardisson (Talk | contribs)
(Available Templates - add new NeoVer template to list, for non-Main Page usages of the NeoOffice Classic Edition version number)
 
(28 intermediate revisions not shown.)
Line 3: Line 3:
=== Information on Editing and Wiki Syntax === === Information on Editing and Wiki Syntax ===
-* From the Media Wiki site+* From the MediaWiki site
 +:http://meta.wikimedia.org/wiki/Help:Reference_card
:http://meta.wikimedia.org/wiki/Help:Editing :http://meta.wikimedia.org/wiki/Help:Editing
:http://meta.wikimedia.org/wiki/Help:Table :http://meta.wikimedia.org/wiki/Help:Table
Line 18: Line 19:
* Keep the pages short. If a page is long, it probably contains too many subjects and should be split into two or more pages. * Keep the pages short. If a page is long, it probably contains too many subjects and should be split into two or more pages.
* MediaWiki splits title words on spaces (and transforms them into underscores in page URLs). Name new pages with a descriptive title.<br> * MediaWiki splits title words on spaces (and transforms them into underscores in page URLs). Name new pages with a descriptive title.<br>
-:'''NeoJInfo''' is a bad page name/title. +*:'''NeoJInfo''' is a bad page title.
-:'''Information about NeoOffice''' or '''NeoOffice Information''' are good page names/titles.+*:'''Information about NeoOffice''' or '''NeoOffice Information''' are good page titles.
 +* Both title case ([[Adding a Search Control to a Form]]) and sentence case ([[Contributing to the NeoOffice projects]]) are acceptable for page titles the English wiki. For page titles with a large number of words (more than a half-dozen or so), sentence case is slightly more popular; for shorter titles, title case is preferred. (See [[#Style and Formatting Guide|Style and Formatting Guide]] for section titles.)
 +* Try to avoid using most non-alphanumeric characters in page titles, unless such characters are required by your language (e.g. "captures d'écran" in French) or essential to making the title of the article clear. Hyphens and periods are OK, but characters such as commas, semi-colons, quotes, and parentheses should be avoided. Colons should only be used for pages in Namespaces (such as [[Help:Contents]]) or our language pseudo-namespaces (e.g., [[Fr:Accueil]]).
* '''Do not choose page titles which end with ''scp'' or ''ftp'' or other well-known internet protocols, or common extensions for executable files (''exe'');''' the server will not display those pages. * '''Do not choose page titles which end with ''scp'' or ''ftp'' or other well-known internet protocols, or common extensions for executable files (''exe'');''' the server will not display those pages.
* Always add a comment (summary) of your change. * Always add a comment (summary) of your change.
* When adding a new page, be sure to include the appropriate [[Special:Categories|Category]] tag(s) on the page. * When adding a new page, be sure to include the appropriate [[Special:Categories|Category]] tag(s) on the page.
-* Join us in [[Talk:Main_Page]] for the latest wiki-team info!+* For discussion or questions, post on the Talk (discussion) page for the article or editor in question (for discussion around a specific edit), or start a new thread in the [http://trinity.neooffice.org/modules.php?name=Forums&file=viewforum&f=16 NeoWiki forum at trinity].
* '''Rebranding''': consult the [[Rebranding]] page for the latest info about rebranding NeoOffice/J as NeoOffice in the wiki * '''Rebranding''': consult the [[Rebranding]] page for the latest info about rebranding NeoOffice/J as NeoOffice in the wiki
 +* When linking to a page at [http://www.neooffice.org www.neooffice.org], '''English pages must use language-agnostic urls''', e.g. http://www.neooffice.org/neojava/download.php instead of http://www.neooffice.org/neojava/en/download.php
 +*: Doing so allows redirecting to a user's preferred language if it exists on www.neooffice.org.
 +** When linking to a section on a page (an anchor), e.g. http://www.neooffice.org/neojava/download.php#installlanguages, use the following format instead to work-around a Safari bug: http://www.neooffice.org/neojava/download.php?fragment=installlanguages
 +* When linking to a post in the [http://trinity.neooffice.org/modules.php?name=Forums Trinity forums], prefer the '''http''' URL (Trinity current will redirect logged in or logged out users as appropriate, but old links are all '''http''' and most visitors are likely not going to be logged-in users).
===Style and Formatting Guide=== ===Style and Formatting Guide===
Line 31: Line 38:
*'''Menus''', '''submenus''', and '''menu items''' - always use sentences, not "->" or other shorthand. And not just sentences, but sentences that instruct the user on what to do (pull down menus, select buttons, check boxes, etc.) '''in the order that they appear to the user'''. E.g., "In the '''View''' menu, under '''Toolbars''', select '''Customize'''." Names of the menu, submenu, or item are '''boldface'''. *'''Menus''', '''submenus''', and '''menu items''' - always use sentences, not "->" or other shorthand. And not just sentences, but sentences that instruct the user on what to do (pull down menus, select buttons, check boxes, etc.) '''in the order that they appear to the user'''. E.g., "In the '''View''' menu, under '''Toolbars''', select '''Customize'''." Names of the menu, submenu, or item are '''boldface'''.
 +** Use the {{Menu|Menu}} template: <tt><nowiki>{{menu|Name of Menu or Menu Item}}</nowiki></tt>
-*"Dialogue/window titles" or "Preference Option Name" - currently, sometimes '''boldface''', sometimes in "quotes"+*"Dialogue/window titles" or "Preference Option Name" - <s>currently, sometimes '''boldface''', sometimes in "quotes"</s>
-*: The format for the above elements has yet to be frozen; they should stand out but also more easily be distinguished from menus and filenames.+*: <s>The format for the above elements has yet to be frozen; they should stand out but also more easily be distinguished from menus and filenames.</s>
- +** Use the {{Window|Window}} template for dialogue/window titles: <tt><nowiki>{{Window|Title of Window}}</nowiki></tt>
-* Buttons - this format needs to decided upon yet. For now, treat as above.+** Use the {{prefName|prefName}} template for preferences/options (selecting a radio button, checkbox, or item from a pop-up menu): <tt><nowiki>{{prefName|Text of Preference/Option}}</nowiki></tt>
 +** Use the {{section|Section}} template for names of sub-sections in different preference windows (e.g. Printer Warnings in the Print preferences) or for tabs in a tabbed window: <tt><nowiki>{{section|Name of Preference Section or Tab}}</nowiki></tt>
 +**: ''See [[:Image:Section_vs_prefName.png]] for an illustration.
 +**: Also use the {{section|Section}} template for names of items in the sidebar in the Preferences window (e.g., "NeoOffice Writer" or "Tables")
 +* Buttons - <s>this format needs to decided upon yet. For now, treat as above.</s>
 +** Use the {{button|Button}} template: <tt><nowiki>{{button|Name of Button}}</nowiki></tt>
 +* Keyboard commands (e.g., pressing {{key|return}} or {{key|⌘-S}}, but '''not''' typing a string of text): <tt><nowiki>{{key|name of key/shortcut combination}}</nowiki></tt>
*'''Filenames''' - standalone—not part of a path—should be '''boldface'''. *'''Filenames''' - standalone—not part of a path—should be '''boldface'''.
 +** '''Application Names''' - when referring to another application in an article (e.g., "Open '''Activity Monitor''' and click…"), use '''boldface'''.
*<tt>Paths</tt> (including paths ending with a filename) or <tt>Terminal commands</tt> - use the <nowiki><tt></nowiki><tt>typewriter</tt><nowiki></tt></nowiki> tag for single lines or, heaven forbid, the <nowiki><pre></nowiki><pre>preformatted text</pre><nowiki></pre></nowiki> tag for blocks of code. *<tt>Paths</tt> (including paths ending with a filename) or <tt>Terminal commands</tt> - use the <nowiki><tt></nowiki><tt>typewriter</tt><nowiki></tt></nowiki> tag for single lines or, heaven forbid, the <nowiki><pre></nowiki><pre>preformatted text</pre><nowiki></pre></nowiki> tag for blocks of code.
 +
 +* For section titles, both title case (e.g. [[Using_Macros#Recording_a_Simple_Macro|Recording a Simple Macro]]) and sentence case ([[Using_Character_Styles#How_to_create_a_character_style|How to create a character style]]) are acceptable for the English wiki. Be consistent within an individual article. Note that if you are cleaning up an existing article, other articles might link to the existing section names, so perform due diligence to find and correct those links when cleaning up.
* Use ''NeoOffice'' and ''OpenOffice.org'', not ''Neo'' and ''OOo'' (in certain cases, such as the trademark guidelines or press materials, use ''NeoOffice®'' instead). * Use ''NeoOffice'' and ''OpenOffice.org'', not ''Neo'' and ''OOo'' (in certain cases, such as the trademark guidelines or press materials, use ''NeoOffice®'' instead).
Line 46: Line 63:
** When adding items to '''Discussion''' (Talk:) pages, '''do sign your additions/comments'''. ** When adding items to '''Discussion''' (Talk:) pages, '''do sign your additions/comments'''.
-====Mac vs. Windows/*nix====+====Mac vs. Windows/Unix/Linux Conventions====
-Since the goal of Neo/J is making OOo more Mac-like, we should always prefer "Mac conventions" where possible; e.g., sending someone to the ''Activity Monitor'' utility to quit a hung process instead of <tt>ps -aux | grep blah</tt>, and using the '''Preferences...''' item in the '''NeoOffice''' menu rather than the Windows-like '''Tools''' menu, '''Options''' item.+Since the goal of NeoOffice is making OpenOffice.org more Mac-like, we should always prefer "Mac conventions" where possible; e.g., sending someone to the '''Activity Monitor''' utility to quit a hung process instead of <tt>ps -aux | grep blah</tt>, and using the {{menu|Preferences…}} item in the {{menu|NeoOffice}} menu rather than the Windows-like {{menu|Tools}} menu, {{menu|Options}} item.
-If something can't be done (or can't be done as easily) without firing up the ''Terminal'', fine, but let's prefer Mac-friendly instructions. (This also conforms with Waldo's points 3-6 in the style guide discussion.)+If something can't be done (or can't be done as easily) without firing up the ''Terminal'', fine, but let's prefer Mac-friendly instructions. (This also conforms with Waldo's points 3-6 in the [[Help_talk:Editing#Style Guide Discussion|style guide discussion]].)
 + 
 +===Fixme articles===
 + 
 +We employ the [[Template:fixme|fixme template]] and its localized equivalents (see [[#Available Templates|below]]) to indicate articles that are in need of work. Sometimes an article is only in need of style fixes, or changes such as turning a quick list of facts into a readable article; sometimes the content needs updating for changes in NeoOffice or Mac OS X, but sometimes the article needs a complete rewrite.
 + 
 +Also, when making a significant update to an English page that is translated, NeoWiki editors usually try to mark the corresponding translations with those languages' fixme templates to make sure the translators know to update their translations.
 + 
 +If you understand the changes that need to be made and have made them, you should remove the fixme template from the article. If you're unsure what changes need to be made to an article, or if your editing has fixed the article, ask in the [https://trinity.neooffice.org/modules.php?name=Forums&file=viewforum&f=16 NeoWiki forum] on trinity.
===Notes about URLs in Templates=== ===Notes about URLs in Templates===
Line 60: Line 85:
Conversion (hexadecimal ASCII value with a percent sign in front): Conversion (hexadecimal ASCII value with a percent sign in front):
- " # $ % &amp;<!-- --> ' * , : ; < > [ ] ^ ` { | } ? =+ " # $ % &amp;<!-- --> ' ( ) * , : ; < > [ ] ^ ` { | } ? =
- %22 %23 %24 %25 %26 <!-- -->%27 %2a %2c %3a %3b %3c %3e %5b %5d %5e %60 %7b %7c %7d %3f %3d+ %22 %23 %24 %25 %26 <!-- -->%27 %28 %29 %2a %2c %3a %3b %3c %3e %5b %5d %5e %60 %7b %7c %7d %3f %3d
===Available Templates=== ===Available Templates===
-Here is a list of the templates already started for the NeoWiki. (As time permits, I will try to better document the use of them) +Here is an incomplete list of the templates already started for the NeoWiki. (As time permits, we will try to better document the use of them)
[http://meta.wikimedia.org/wiki/Help:Template Editing help for Templates] [http://meta.wikimedia.org/wiki/Help:Template Editing help for Templates]
Line 70: Line 95:
See also [[Guidelines for Translating the NeoWiki#Notes]] for information on translating templates and the new and deprecated naming schemes for such templates. See also [[Guidelines for Translating the NeoWiki#Notes]] for information on translating templates and the new and deprecated naming schemes for such templates.
-''([[User:Jake|Jake]] and [[User:PhilippePerret|Phillipe]] have added several new templates recently [Nov 2005]) - [http://neowiki.sixthcrusade.com/index.php?title=Special%3AAllpages&from=&namespace=10 All Templates]''+''([[User:Jake|Jake]] and [[User:PhilippePerret|Phillipe]] have added several new templates recently [Nov 2005]) - [https://neowiki.neooffice.org/index.php?title=Special:Allpages&from=&namespace=10 All Templates]''
'''Administrative Templates''' '''Administrative Templates'''
-* [[Template:Fixme]], [[Template:Fr:Fixme]] - adds a note to a page needing updates and adds the page to the "Fixme" category+* [[Template:Fixme]], [[Template:Fr:Fixme]], [[Template:de:Fixme]], [[Template:it:Fixme]], [[Template:es:Fixme]] - adds a note to a page needing updates and adds the page to the "Fixme" category
 +* [[Template:InTranslation]] - adds a note to the top of the page indicating the article is being translated and the full text can be found in one or more other languages
 +* [[Template:LastUpdated]] - adds a "Last Updated:" note at the top of a page (for semi-stable pages that do sometimes get substantive updates, like the [[NeoOffice 2.1 Press Kit]] or [[NeoOffice Feature Comparison]]) with the date of the last ''substantive'' change.
 +* [[Template:Obsolete]] - adds a note to a page indicating that the page is obsolete (used for pages describing discontinued applications)
'''Formatting templates''' '''Formatting templates'''
-* [[Template:Bluebox]] - used on [[Main Page]] and in the [[NeoOffice/J Press Kit]]+* [[Template:Bluebox]] - used on [[Main Page]] and in the [[NeoOffice 2.1 Press Kit]]
 +*: This template is designed to work only by including another page; if you want to use the bluebox style for free-form text, use [[Template:Bluebox2]] instead
* [[Template:Alertbox]] - used for critical alerts * [[Template:Alertbox]] - used for critical alerts
* [[Template:redbox]] - used for important notices (non-critical) * [[Template:redbox]] - used for important notices (non-critical)
Line 82: Line 111:
* [[Template:Yellowcolumn]] - actually pink, used on new [[Main Page]] * [[Template:Yellowcolumn]] - actually pink, used on new [[Main Page]]
* [[Template:Dashedbox]] * [[Template:Dashedbox]]
 +* [[Template:preBox]] - used to wrangle multi-line pre-formatted text into lists, such as [[Troubleshooting_Tips#Check_for_a_corrupt_Java_installation|here]]
* [[Template:Handbook sidebar]] * [[Template:Handbook sidebar]]
* [[Template:Imagebox]] * [[Template:Imagebox]]
Line 106: Line 136:
* [[template:x11sidebar]] - menu for the side of X11 pages * [[template:x11sidebar]] - menu for the side of X11 pages
* [[Template:NeoPatchVer]] - neo patch version * [[Template:NeoPatchVer]] - neo patch version
 +* [[Template:NeoEAPPatchVer]] - EAP patch version
 +* [[Template:NeoLegPatchVer]] - legacy release patch version (e.g., Neo 2.2.6 for 10.3.9)
 +* [[Template:EAPversion]], [[Template:EAPend]], [[Template:EAPstart]] - for any EAP date or version references
* [[Template:oooversion]] - OOo version * [[Template:oooversion]] - OOo version
 +* [[Template:Retroversion]] - RetroOffice version
 +* [[Template:NeoMASVer]] - NeoOffice Mac App Store version
 +* [[Template:NeoVer]] - NeoOffice Classic Edition version (non-[[Main Page]] usages; currently updated via [[Template:NeoMainPageVer]])
 +* [[Template:NeoMainPageVer]] - Current stable, non-EA NeoOffice release; this template is for Main Page (English and localized) use only!
 +* [[Template:NeoOOoVer]] - OOo version used by the current stable, non-EA NeoOffice release; this template is for Main Page (English and localized) use only!
 +
====Wiki Translation Templates==== ====Wiki Translation Templates====
There are also a series of style and content templates specific to the wiki translation efforts; see [[Guidelines for Translating the NeoWiki]] for more info about these templates. Please do not replace these templates with other templates or use these templates for other purposes. A non-exhaustive list (will grow as more languages are added) follows. There are also a series of style and content templates specific to the wiki translation efforts; see [[Guidelines for Translating the NeoWiki]] for more info about these templates. Please do not replace these templates with other templates or use these templates for other purposes. A non-exhaustive list (will grow as more languages are added) follows.
Content Content
-* [[Template:OtherLangsEN]], [[Template:OtherLangsFR]]+* [[Template:OtherLangs]], [[Template:fr:OtherLangs]], [[Template:de:OtherLangs]], [[Template:it:OtherLangs]], [[Template:es:OtherLangs]]
Formatting Formatting
Line 123: Line 162:
== Style Guide Discussion == == Style Guide Discussion ==
-''We should eventually move this section into Help:Editing:Discussion''+For details about how we arrived at these rules and other discussion of the Style Guide, see [[Help_talk:Editing#Style_Guide_Discussion|Style Guide Discussion]] on this article's Discussion page.
- +
-Do we need to have a "style guide" to standardize how we represent certain functions or types of info? +
- +
-We have three "regular editors" now, plus a fair amount of legacy content from the old wiki (which had another handful of editors/contributors). We seem to represent only one type of thing consistently among the three of us + legacy content:+
- +
-*<tt>paths</tt> (incl. paths ending with a filename) or <tt>terminal commands</tt>+
- +
-Other things seem to vary widely:+
- +
-*'''Menus''' '''submenus''' (: or -> or something else) [[User:Waldo|Waldo]] says always use sentences, not "->". And not just sentences, but sentences that instruct the user on what to do (pull down menus, select buttons, check boxes, etc.) '''in the order that they appear to the user'''. Ie, "In the '''View''' menu, under '''Toolbars''', select '''Customize'''."+
- +
-*'''Menus''' (standalone in text, i.e., Choose the Tools menu--sometimes '''boldface''')+
- +
-*'''Filenames''' (standalone--should be '''boldface''')+
- +
-*"Dialogue/window titles" or "Preference Option Name" (sometimes '''boldface''', sometimes in "quotes")+
- +
-Should we agree on a wiki style for the latter types and adhere to it from here on out, and clean up the older stuff as we get time or modify those article?+
- +
---[[User:Sardisson|sardisson]] 04:27, 29 Apr 2005 (CDT)+
- +
-Good question. Having worked on a Gentoo wiki or too, i have to say I was impressed with their [http://gentoo-wiki.com/Template_Listing templates] that give a unified look to the whole thing. I think a style guide is not a bad idea.. here are some suggestions.+
- +
-# bold all filenames, menu items, application names, or any text string that appears on-screen. this will facilitate readability tremendously, especially when following instructions.+
-# put "pre" or "tt" tags around all typed Terminal commands (or use something similar to the gentoo templates.)+
-# When describing procedures to be done that involve rooting through menus, list the menu items in the order they appear to the user. for example: "In the menu bar, under the '''File''' item, select '''Save'''."+
-# I think that writing directions out in English has several advantages over the "Item 1 > Item 2" method of indicating options/navigation. For one thing, there is not much room for misunderstanding when you say "Make sure that the '''whatever''' radio button is selected." or "Press the '''Ok''' button to continue." Also, it is more accessible, I think, to a newbie user who may not be familiar with the 'item->item' shorthand.+
-# When issuing a series of instructions, I think it's always a good idea to express to the user what will happen next, ie "Press the '''Ok''' button. A window labeled '''Preferences''' will appear."+
- +
-I'm sure I'll think of more style stuff... this is just a start.. I think the gentoo wiki templates really help unify the site and the navigation stuff facilitates site organization and helps you get around easily.+
- +
---[[User:Waldo|Waldo]] 04:46, 29 Apr 2005 (CDT)+
- +
-FWIW here is a [http://gentoo-wiki.com/HOWTO_Update_to_GNOME_2.10 sample HOWTO] I wrote for gentoo. This was the first one I wrote, and it was really easy w/the templates... see how it fits w/the entire site?+
- +
---[[User:Waldo|Waldo]] 05:25, 29 Apr 2005 (CDT)+
- +
-I'd really like to differentiate window/item titles from filenames and menus; otherwise, I've updated my list of style to match Waldo's text description.+
- +
---[[User:Sardisson|sardisson]] 22:34, 2 May 2005 (CDT) +
- +
-===Mac vs. Windows/*nix===+
- +
-Since the goal of Neo/J is making OOo more Mac-like, we should always prefer "Mac conventions" where possible; e.g., sending someone to the ''Activity Monitor'' utility to quit a hung process instead of <tt>ps -aux | grep blah</tt>, and using the '''Preferences...''' item in the '''NeoOffice''' menu rather than the Windows-like '''Tools''' menu, '''Options''' item.+
- +
-If something can't be done (or can't be done as easily) without firing up the ''Terminal'', fine, but let's prefer Mac-friendly instructions. This also conforms with Waldo's points 3-6 above.+
- +
---[[User:Sardisson|sardisson]] 04:51, 14 Jul 2005 (CDT)+
- +
-{{botlangbarEN|[[Fr:Aide_pour_l'Édition_de_NeoWiki|Français]] [[It:Aiuto:Modificare_il_Wiki|Italiano]] [[Es:guía de estilo|Español]]}}+{{botlangbarEN|[[Fr:Aide_pour_l'Édition_de_NeoWiki|Français]] [[It:Aiuto:Modificare_il_Wiki|Italiano]] [[Es:guía de estilo|Español]] [[nl:Help:Editing|Nederlands]]}}
[[Category:Administrativa]][[Category:Contributing]][[Category:NeoOffice]] [[Category:Administrativa]][[Category:Contributing]][[Category:NeoOffice]]

Current revision

To request a user account for this wiki, please follow the steps on the New User page.

Contents

Information on Editing and Wiki Syntax

  • From the MediaWiki site
http://meta.wikimedia.org/wiki/Help:Reference_card
http://meta.wikimedia.org/wiki/Help:Editing
http://meta.wikimedia.org/wiki/Help:Table
  • From the Wikipedia
http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page

Stylistic and Editorial Policies for the NeoWiki

had some rules on the old wiki. They went something like:

  • Keep the pages short. If a page is long, it probably contains too many subjects and should be split into two or more pages.
  • MediaWiki splits title words on spaces (and transforms them into underscores in page URLs). Name new pages with a descriptive title.
    NeoJInfo is a bad page title.
    Information about NeoOffice or NeoOffice Information are good page titles.
  • Both title case (Adding a Search Control to a Form) and sentence case (Contributing to the NeoOffice projects) are acceptable for page titles the English wiki. For page titles with a large number of words (more than a half-dozen or so), sentence case is slightly more popular; for shorter titles, title case is preferred. (See Style and Formatting Guide for section titles.)
  • Try to avoid using most non-alphanumeric characters in page titles, unless such characters are required by your language (e.g. "captures d'écran" in French) or essential to making the title of the article clear. Hyphens and periods are OK, but characters such as commas, semi-colons, quotes, and parentheses should be avoided. Colons should only be used for pages in Namespaces (such as Help:Contents) or our language pseudo-namespaces (e.g., Fr:Accueil).
  • Do not choose page titles which end with scp or ftp or other well-known internet protocols, or common extensions for executable files (exe); the server will not display those pages.
  • Always add a comment (summary) of your change.
  • When adding a new page, be sure to include the appropriate Category tag(s) on the page.
  • For discussion or questions, post on the Talk (discussion) page for the article or editor in question (for discussion around a specific edit), or start a new thread in the NeoWiki forum at trinity.
  • Rebranding: consult the Rebranding page for the latest info about rebranding NeoOffice/J as NeoOffice in the wiki
  • When linking to a page at www.neooffice.org, English pages must use language-agnostic urls, e.g. http://www.neooffice.org/neojava/download.php instead of http://www.neooffice.org/neojava/en/download.php
    Doing so allows redirecting to a user's preferred language if it exists on www.neooffice.org.
  • When linking to a post in the Trinity forums, prefer the http URL (Trinity current will redirect logged in or logged out users as appropriate, but old links are all http and most visitors are likely not going to be logged-in users).

Style and Formatting Guide

When adding new information to the wiki or editing existing information, always adhere to the NeoWiki Style guidelines below:

  • Menus, submenus, and menu items - always use sentences, not "->" or other shorthand. And not just sentences, but sentences that instruct the user on what to do (pull down menus, select buttons, check boxes, etc.) in the order that they appear to the user. E.g., "In the View menu, under Toolbars, select Customize." Names of the menu, submenu, or item are boldface.
    • Use the Menu template: {{menu|Name of Menu or Menu Item}}
  • "Dialogue/window titles" or "Preference Option Name" - currently, sometimes boldface, sometimes in "quotes"
    The format for the above elements has yet to be frozen; they should stand out but also more easily be distinguished from menus and filenames.
    • Use the Window template for dialogue/window titles: {{Window|Title of Window}}
    • Use the prefName template for preferences/options (selecting a radio button, checkbox, or item from a pop-up menu): {{prefName|Text of Preference/Option}}
    • Use the Section template for names of sub-sections in different preference windows (e.g. Printer Warnings in the Print preferences) or for tabs in a tabbed window: {{section|Name of Preference Section or Tab}}
      See Image:Section_vs_prefName.png for an illustration.
      Also use the Section template for names of items in the sidebar in the Preferences window (e.g., "NeoOffice Writer" or "Tables")
  • Buttons - this format needs to decided upon yet. For now, treat as above.
    • Use the Button template: {{button|Name of Button}}
  • Keyboard commands (e.g., pressing return or ⌘-S, but not typing a string of text): {{key|name of key/shortcut combination}}
  • Filenames - standalone—not part of a path—should be boldface.
    • Application Names - when referring to another application in an article (e.g., "Open Activity Monitor and click…"), use boldface.
  • Paths (including paths ending with a filename) or Terminal commands - use the <tt>typewriter</tt> tag for single lines or, heaven forbid, the <pre>
    preformatted text
    </pre> tag for blocks of code.
  • For section titles, both title case (e.g. Recording a Simple Macro) and sentence case (How to create a character style) are acceptable for the English wiki. Be consistent within an individual article. Note that if you are cleaning up an existing article, other articles might link to the existing section names, so perform due diligence to find and correct those links when cleaning up.
  • Use NeoOffice and OpenOffice.org, not Neo and OOo (in certain cases, such as the trademark guidelines or press materials, use NeoOffice® instead).
  • While the MediaWiki editing guidelines referenced above call for authors and editors to always sign contributions, the NeoWiki does not adhere to that practice in articles. Similar to an encyclopedia, we want to present a unified article, unbroken by editing dates and user signatures.
    • When adding items to Discussion (Talk:) pages, do sign your additions/comments.

Mac vs. Windows/Unix/Linux Conventions

Since the goal of NeoOffice is making OpenOffice.org more Mac-like, we should always prefer "Mac conventions" where possible; e.g., sending someone to the Activity Monitor utility to quit a hung process instead of ps -aux | grep blah, and using the Preferences… item in the NeoOffice menu rather than the Windows-like Tools menu, Options item.

If something can't be done (or can't be done as easily) without firing up the Terminal, fine, but let's prefer Mac-friendly instructions. (This also conforms with Waldo's points 3-6 in the style guide discussion.)

Fixme articles

We employ the fixme template and its localized equivalents (see below) to indicate articles that are in need of work. Sometimes an article is only in need of style fixes, or changes such as turning a quick list of facts into a readable article; sometimes the content needs updating for changes in NeoOffice or Mac OS X, but sometimes the article needs a complete rewrite.

Also, when making a significant update to an English page that is translated, NeoWiki editors usually try to mark the corresponding translations with those languages' fixme templates to make sure the translators know to update their translations.

If you understand the changes that need to be made and have made them, you should remove the fixme template from the article. If you're unsure what changes need to be made to an article, or if your editing has fixed the article, ask in the NeoWiki forum on trinity.

Notes about URLs in Templates

When including URLs to trinity (or similar pages with ? = & and other characters in them) in templates directly, the characters must be encoded or they'll fubar the display of the template (it seems the = are the most problematic; who'd have thought!?):

From MediaWiki, with a few additions they missed:

Conversion (hexadecimal ASCII value with a percent sign in front):

 "   #   $   %   &   '   (   )   *   ,   :   ;   <   >   [   ]   ^   `   {   |   }   ?   =
%22 %23 %24 %25 %26 %27 %28 %29 %2a %2c %3a %3b %3c %3e %5b %5d %5e %60 %7b %7c %7d %3f %3d

Available Templates

Here is an incomplete list of the templates already started for the NeoWiki. (As time permits, we will try to better document the use of them)

Editing help for Templates

See also Guidelines for Translating the NeoWiki#Notes for information on translating templates and the new and deprecated naming schemes for such templates.

( and Phillipe have added several new templates recently [Nov 2005]) - All Templates

Administrative Templates

Formatting templates

Content Templates

Wiki Translation Templates

There are also a series of style and content templates specific to the wiki translation efforts; see Guidelines for Translating the NeoWiki for more info about these templates. Please do not replace these templates with other templates or use these templates for other purposes. A non-exhaustive list (will grow as more languages are added) follows.

Content

Formatting

Sandbox

established the Test page for everyone to use to try out editing and wiki techniques without fear of messing up any of the existing pages. If you want to experiment with how the wiki works, do so on that page.


Style Guide Discussion

For details about how we arrived at these rules and other discussion of the Style Guide, see Style Guide Discussion on this article's Discussion page.


This article in other languages: Français Italiano Español Nederlands
Personal tools