|
|
Help:Editing
From NeoWiki
| Revision as of 09:51, 14 July 2005 (edit) Sardisson (Talk | contribs) (Mac vs. Windows/*nix conventions in instructions) ← Previous diff |
Revision as of 07:25, 15 August 2005 (edit) (undo) Sardisson (Talk | contribs) (separate the "style guide" from the "discussion on what to implement as a style guide) Next diff → |
||
| Line 14: | Line 14: | ||
| * 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 underscores. 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 name/title. | ||
| - | :''' | + | :'''Information about NeoOffice/J''' or '''NeoOffice/J Information''' are good page names/titles. |
| * 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 Category tag(s) on the page. | ||
| * Join us in [[Talk:Main_Page]] for more rules and the latest wiki-team info! | * Join us in [[Talk:Main_Page]] for more rules and the latest wiki-team info! | ||
| + | |||
| == Style/Formatting Guide == | == Style/Formatting Guide == | ||
| + | |||
| + | When adding new information to the wiki or editing existing information, always adhere to the NeoWiki Style guidelines below: | ||
| + | |||
| + | *<tt>Paths</tt> (including paths ending with a filename) or <tt>Terminal commands</tt> - use the <nowiki><tt>typewriter</tt></nowiki> tag for single lines or, heaven forbid, the <nowiki><pre>preformatted</pre></nowiki> tag for blocks of code. | ||
| + | |||
| + | *'''Menus''' '''submenus''' - 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'''." | ||
| + | |||
| + | *'''Menus''' and '''menu items''' - standalone in text, i.e., Choose the '''Tools''' menu, are '''boldface'''. | ||
| + | |||
| + | *'''Filenames''' - standalone—not part of a path—should be '''boldface'''. | ||
| + | |||
| + | *"Dialogue/window titles" or "Preference Option Name" - sometimes '''boldface''', sometimes in "quotes" | ||
| + | *: The format for these elements has yet to be frozen; they should more easily be distinguished from menus and filenames. | ||
| + | |||
| + | * Use "NeoOffice/J" and "OpenOffice.org", not Neo/J (or NeoOffice) and OOo (in certain cases, such as the trademark guidelines or press materials, use NeoOffice®/J instead). | ||
| + | |||
| + | ===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/J''' 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 below.) | ||
| + | |||
| + | === Notes about URLs in Templates === | ||
| + | |||
| + | When including URLs to trinity (or similar pages with '''? = &''' and other characters in them) in '''templates''', 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 [http://meta.wikimedia.org/wiki/Help:URL#URLs_in_external_links MediaWiki], with a few additions they missed: | ||
| + | |||
| + | Conversion (hexadecimal ASCII value with a percent sign in front): | ||
| + | |||
| + | " # $ % &<!-- --> ' * , : ; < > [ ] ^ ` { | } ? = | ||
| + | %22 %23 %24 %25 %26 <!-- -->%27 %2a %2c %3a %3b %3c %3e %5b %5d %5e %60 %7b %7c %7d %3f %3d | ||
| + | |||
| + | |||
| + | |||
| + | ==Sandbox== | ||
| + | |||
| + | [[User:Jake|Jake]] 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 == | ||
| Do we need to have a "style guide" to standardize how we represent certain functions or types of info? | Do we need to have a "style guide" to standardize how we represent certain functions or types of info? | ||
| Line 70: | Line 113: | ||
| --[[User:Sardisson|sardisson]] 04:51, 14 Jul 2005 (CDT) | --[[User:Sardisson|sardisson]] 04:51, 14 Jul 2005 (CDT) | ||
| - | === Notes about URLs in Templates === | ||
| - | |||
| - | When including URLs to trinity (or similar pages with '''? = &''' and other characters in them) in '''templates''', 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 [http://meta.wikimedia.org/wiki/Help:URL#URLs_in_external_links MediaWiki], with a few additions they missed: | ||
| - | |||
| - | Conversion (hexadecimal ASCII value with a percent sign in front): | ||
| - | |||
| - | " # $ % &<!-- --> ' * , : ; < > [ ] ^ ` { | } ? = | ||
| - | %22 %23 %24 %25 %26 <!-- -->%27 %2a %2c %3a %3b %3c %3e %5b %5d %5e %60 %7b %7c %7d %3f %3d | ||
| - | |||
| - | |||
| - | |||
| - | === Sandbox === | ||
| - | |||
| - | [[User:Jake|Jake]] 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. | ||
| [[Category:Contributing]] | [[Category:Contributing]] | ||
| [[Category:NeoOffice/J]] | [[Category:NeoOffice/J]] | ||
Revision as of 07:25, 15 August 2005
Contents |
Information on Editing and Wiki Syntax
- From the Media Wiki site
- From the Wikipedia
Stylistic and Editing 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 name/title.
- Information about NeoOffice/J or NeoOffice/J Information are good page names/titles.
- 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.
- Join us in Talk:Main_Page for more rules and the latest wiki-team info!
Style/Formatting Guide
When adding new information to the wiki or editing existing information, always adhere to the NeoWiki Style guidelines below:
- 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</pre> tag for blocks of code.
- Menus submenus - 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."
- Menus and menu items - standalone in text, i.e., Choose the Tools menu, are boldface.
- Filenames - standalone—not part of a path—should be boldface.
- "Dialogue/window titles" or "Preference Option Name" - sometimes boldface, sometimes in "quotes"
- The format for these elements has yet to be frozen; they should more easily be distinguished from menus and filenames.
- Use "NeoOffice/J" and "OpenOffice.org", not Neo/J (or NeoOffice) and OOo (in certain cases, such as the trademark guidelines or press materials, use NeoOffice®/J instead).
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 ps -aux | grep blah, and using the Preferences... item in the NeoOffice/J 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 below.)
Notes about URLs in Templates
When including URLs to trinity (or similar pages with ? = & and other characters in them) in templates, 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 %2a %2c %3a %3b %3c %3e %5b %5d %5e %60 %7b %7c %7d %3f %3d
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
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:
- paths (incl. paths ending with a filename) or terminal commands
Other things seem to vary widely:
- Menus submenus (: or -> or something else) 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?
--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 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.
--Waldo 04:46, 29 Apr 2005 (CDT)
FWIW here is a 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?
--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.
--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 ps -aux | grep blah, and using the Preferences... item in the NeoOffice/J 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.
--sardisson 04:51, 14 Jul 2005 (CDT)
