|
Finding information in the wiki
Use the navigation aids in the wiki to help you find information. The following navigational aids are available:
- Home, Product documentation, and Learning center tabs
- Article views
- Search and Advanced search
- Categories
- Tag cloud
- Media Gallery
In addition, the home page contains a list of helpful or frequently used links to help you find information quickly.
Tabs
The Home tab is the main entry point and default view into the wikis.
The Product documentation tab takes you to a product documentation category page where you can see a list of all of the available product documentation for the product. Some of the links take you to documentation within the wiki, and some links will go to external sites. Both types of links are clearly marked.
The Learning Center tab contains resources such as demonstrations, videos, tutorials, reference cards, and Web seminars to help you get started using the product.
Article views
Use article views to globally sort articles in the wiki.
These views will return wiki articles from all categories, sorted by the view you selected. For example, Recently edited articles will display all articles that have been edited, sorted by most recently edited.
Search and Advanced Search
Search
Search finds articles that contain all the words you specify. The words may occur in any order in the article and need not be contiguous.
The search is case-insensitive: the case of the specified words does not matter.
Search does not currently support:
- Literal or exact searches, in which the search words are enclosed in quotes, like "my dog". However, searching for "my dog" without the quotes will find articles
that contain the phrase "my dog".
- Boolean searches, in which the search words are separated by operators like AND and OR. These operators are treated like ordinary words, so searching for
"my AND dog" returns articles that contain the words "my", "and", and "dog".
Advanced search
Advanced search enables you narrow your search by specifying more criteria. You can restrict your search to a specific author, to a time frame, a selection of categories, or even specific tags.
The advanced search page provides full instructions on how to use it.
Categories
Categories are located on the left side of the wiki and are used to sort articles into logical groupings.
Click on the name of a category to navigate to that category page.
From the category page, you can sort the articles in the view using the tabs.
You can also specify how many results per page you want to show.
Tag cloud
The tag cloud is available from the Home page, and from the wiki views pages.
Use the slider above the cloud to view more or less tags.
A tag's font is relative to the number of articles with that tag. So tags that appear bigger and bolder have more articles associated with them.
Click on a tag to return a list of articles tagged with the selected word.
Product documentation in the wiki
Your wiki might include product documentation, or links to product documentation on sites outside of the wiki.
You can easily find documentation in the wiki by clicking the "Product Documentation" tab at the top of the wiki.
When you choose this tab, a category page displays with links to the available product documentation.
Navigating product documentation in the wiki
When you select a set of documentation that is available within the wiki, a table of contents displays on the left side of the wiki.
Expand and collapse the sections in the table of contents to view articles.
Product documentation is open for editing, however, you can always view the original non-editable version of a piece of documentation by clicking on the link in the top right of a documentation article:
When you are in the original version of a document, the icon changes to look like this:
Notice that in addition to the icon change, there is a link back to the current editable version, and also the Edit article button is hidden.
Viewing and comparing a previous version of an article
To view a previous version of an article, open the article and expand the Versions section at the bottom of the article.
A list of all of the available versions displays, along with the date and time the version was saved, and by whom.
To view a different version, select the number of the version you want to view.
To compare a previous version of an article to a more recent version of an article, use the Compare versions feature at the top of the versions list.
Use the key at the top of the article to distinguish what is deleted content, and what is new or changed content.
Limitations of the version differences tool:
Formatting changes and graphics are not captured. Only text comparisons.
Rolling back to a previous version of an article
The wiki administrators have the ability to rollback articles to previous versions. If you would like an article rolled back to a previous version, click Wiki feedback in the Help section for the footer. In the form include the following information:
- Name of wiki
- Name of the article you want to roll back
- Specific version (date and time) you want to roll back to
- Reason you need to roll back the article
The wiki administrators will review the request and determine if an article roll back is needed.
Translated content
There are several ways to view translated content in the wikis:
- Machine translations of wiki pages
- Articles originally authored in other language
- Translated versions of product documentation
Each type is distinctly different, and is accessed using different methods.
Translating a page
Select a language from the drop down beneath "Translate page".
You will be prompted to agree to the n.Fluent license agreement, then your page and any subsequent pages you visit will be translated into the chosen language.
At any time you can return to English by selecting "Return to English" from the language list.
Articles originally authored in another language
Wikis are open for people to add articles in any language. When a piece of community translated content is available in a wiki, you will see a section on the home page called "Community Translations", which contains links to the translated content.
Translated versions of product documentation
When product documentation is available in the wiki, there will also be a version of the documentation translated into supported languages.
To access these translations, select the set of product documentation you'd like to see. On that documentation set's category page, there will be a link to "IBM translated product documentation" .
Click the link to see which languages are available.
Contributing to the wiki
To add, edit, or comment on an article, you must have a developerWorks Lotus user name and password.
If you have a developerWorks Lotus user name and password, click Log in in the Contribute section on the left side of the wiki.
If you do not have a developerWorks Lotus user name and password, click "register"
On the Lotus Registration form, select "New Registration" and complete and submit the form.
Creating your own articles
1. Click Add an article.
2. Type the article title in the Subject field.
- The subject of your article will become the URL for the article
- Changing the article's subject will not change the URL once it is created and saved.
- The subject of your article can contain any combination of alphanumeric and non-alphanumeric characters, however, if you need to link to an article whose title contains non-alphanumeric characters, only the following characters are supported for linking:
- colon :
- dot .
- comma ,
- apostrophe '
- quotations "
- dash -
3. Type a summary of your article in the Abstract field. This abstract displays in many of the views and helps the reader determine if the article is relevant to their search without having to open the article. If you do not provide an abstract, the first 300 characters of your article will be used instead, including any preliminary text such as subheads or navigation link labels.
4. Select a category and tags to make your article easier to find. Select all that apply.
IMPORTANT: Wiki articles use a style sheet for a consistent look and feel, therefore font changes such as size, color, or font face will be overwritten by the style sheet. If you would like to format text to use a different color, font face, or font size, then use HTML. You can type HTML directly into the Rich Text Editor and the wiki parser will recognize it and render it appropriately when you have saved the article.
Best practice:
Create an initial draft of your wiki article and save it, then go back into the article and edit it to add your content and format it. This will ensure that your article is saved to the database, and that all wiki functionality is available.
Copy/paste
Copying and pasting is supported, however, the formatting may be lost or may render incorrectly in the published article. It is recommended that you copy and paste the content you want to use in your wiki article into a text editor, such as Notepad first, so that any formatting can be removed, then use the capabilities of the RT editor and the available wiki markup options to format your article.
For more information, refer to Tips for porting an MS Word doc to the wiki.
Recommendations
Editing articles
To edit an article, click Edit at the top or bottom of the article. You can use a combination of wiki markup, HTML, and the tools available from the rich text editor to add or modify the content in an article. A wiki markup reference guide is available at the bottom of the article when you are in edit mode.
Commenting on articles
To comment on an article, scroll to the bottom of the article, expand the Comments section, and click Add a comment.
Creating subheadings in a wiki article
You can use wiki markup mixed in with your rich text to get subheadings in your posts, like this:
Wiki markup code for headings:
==My heading 2==
===My heading 3===
====My heading 4====
Headings rendered on the Web:
IMPORTANT: Do not use any kind of formatting on wiki markup. If you do, the markup will not work.
Tips:
- Because of the limitations of the rich text editor, it is best to add your wiki markup for headings first, then add your content to the wiki.
- If your headings don't display properly, the most likely cause is that there is hidden formatting applied to the markup text, which the markup parser can't process. It's always best to create your headings as the first thing you do in the article, then add your text.
- Start with heading 2. Your article will automatically use heading 1 as the article title.
Creating a TOC
When you use wiki markup to designate text as a heading, a table of contents is automatically created at the beginning of the article.
IMPORTANT:
- Do not include any none alpha-numeric characters in the heading text. This can cause the heading markup to be ignored.
- Do not apply any kind of font formatting to the heading text. This will cause the markup to be ignored.
Creating complicated lists
To create create a complicated list (nested bullets, numbers, etc.) you can use the bulleted list and numbered list buttons in the editor's toolbar.
Adding code examples to an article
You can add an incomplete code example within the context of an article, for the purpose of showing an example. To add a code example, use wiki markup:
{code:} <your code example here> {code}
You can use optional size attributes to control the appearance of the code example. Height and width values can be used to create a scrolling area for wide or long sections of code examples.
{code:||height|width} <your code example here>{code}
For example {code:||400|600}<your code sample here> {code}
Where 400 = 400 pixels tall, and 600 = 600 pixels wide
NOTE: If you choose to use size attributes for your code markup, you must ensure that all three (3) pipe characters are present, even if you only use one of the size attributes. The height attribute must come after the second pipe, the width attribute must come after the third pipe.
Below is an example of a long code sample that uses the a and n optional flags, and height value is left blank (but notice that the pipe is still present) and width values 600.
It is recommended that you always use the width attribute and set it to be no greater than 800 pixels to support users with lower screen resolutions.
* The Hello World of the AJAX Search API
*/
google.load('search', '1');
function OnLoad() {
// Create a search control
var searchControl = new google.search.SearchControl();
// Add in a full set of searchers
var localSearch = new google.search.LocalSearch();
searchControl.addSearcher(localSearch);
searchControl.addSearcher(new google.search.WebSearch());
searchControl.addSearcher(new google.search.VideoSearch());
// Set the Local Search center point
localSearch.setCenterPoint("New York, NY");
// tell the searcher to draw itself and tell it where to attach
searchControl.draw(document.getElementById("content"));
// execute an inital search
searchControl.execute("VW GTI");
}
google.setOnLoadCallback(OnLoad);
In code samples, the back slash character requires special handling. Prefix the character with an escape character, like so:
\\
To insert code samples inline with text use the "no wiki" markup option. Surround the text you do not want parsed with three curly braces "{" as shown in the example below:
Doing so will allow characters that are normally interpreted by browsers to pass through as text. For example:
This sentence contains some characters with angle brackets <to>, <from>, <heading>, and <body>.
Note: Working code samples and executables should not be attached to wiki articles. If you have a piece of code that can be executed, please post it in Lotus Greenhouse and link to it from your wiki article. Go to the Lotus Greenhouse website for more information: https://greenhouse.lotus.com/plugins/plugincatalog.nsf/home.xsp
Adding images and attachments to articles
Use the Attachments section at the bottom of the page to attach the graphics, then reference the graphic using wiki markup:
- Expand the Attachments section and select Attach File.
- Browse to the file on your local system and select open.
- Insert a reference to the image in the body of your article using the following syntax:
{{image.file | alt text}}
IMPORTANT: The alt text attribute is required.
Best practices for images:
- All images should be resized in a graphics tool outside the wiki before posting them in the wiki.
- Do not include graphics wider than 640 pixels to avoid any formatting issues. Large images will affect the layout of the page.
Including multimedia in an article
To include multimedia objects, such as video in your wiki article, you first need to post your article on a media hosting site, such as Youtube.
You can then embed the video into the wiki article using the following HTML code in the article:
To embed a .swf file, use this code:
<object width="640" height="480"><param name="movie" value="URL"></param>
<param name="wmode" value="transparent"></param>
<embed src="URL" type="application/x-shockwave-flash" wmode="transparent" width="640" height="480"></embed>
</object>
where "URL" is the URL to the .swf file hosted on a publicly available Web server.
To embed an HTML file that references a .swf, .wmv, or other media file, use this code:
<iframe src="URL" width="1000" height="650"></iframe>
where "URL" is the URL to the .html file hosted on a publicly available Web server.
In addition, to embedded the multimedia in the article, also include a link to open the object full screen in a new window. Use the following code to create this link:
<a href="URL" target="_blank">Watch the demonstration full screen in a new window</a>
where "URL" is the URL to the .html, .swf, .wmv, or other file
Include the word "Video:" at the beginning of the article title to indicate the type of deliverable.
Categorize the wiki article in the Media Gallery category and any other categories that apply to your video.
Appropriately tag your article by product, task, and deliverable type, for example "demo, video" to make your article easier to find.
In the main body of the article, type a description of the video and some instructional text such as "Click the Play button to start the video".
Creating tables
Use wiki markup to create a table using the following syntax:
|= for headings; | for cells:
For example
|=|=column 1|= column 2|=Column 3
|=Row 1|cell 1|cell 2|cell 3
|=Row 2|cell 1|cell 2|cell 3
which renders as follows:
| column 1 | column 2 | Column 3 |
|---|
| Row 1 | cell 1 | cell 2 | cell 3 |
|---|
| Row 2 | cell 1 | cell 2 | cell 3 |
|---|
Linking
Use wiki markup to add links to wiki articles or external links:
To link to a wiki article within the wiki use
Simply use the title of the wiki article to which you want to link.
If you'd like the text for your link to read something different than the article name, for example, "Next topic" in a series, specify an alias after the link:
To link to an external page use
for example
looks like this: IBM
Deleting an article
If you would like an article deleted from the wiki, click Wiki design feedback in the Help section of the footer. In the form include the following information:
*Name of wiki
- Name of the article you want to delete
- Specific version (date and time) you want to delete
- Reason you need to delete the article
Providing feedback on the wiki
We want your feedback! To provide feedback on using the wiki, click Wiki design feedback in the Help section of the footer.
Using feeds and notifications
To receive notification of the latest updates on the wiki, subscribe to an RSS feed by clicking the orange RSS icon in the Subscribe to RSS section on the wiki footer i to subscribe to a RSS feed.
Note: If your browser does not have RSS reading capability built in, or if you do not have an installed feed reader, you will see the raw XML feed when clicking the RSS icon. You must have a feed reader to use the RSS feature of the wiki.
Troubleshooting wiki markup
The following are common issues that might arise while using wiki markup:
Link to a wiki article does not work:
- This can happen if the wiki article's title contains certain non-alphanumeric characters. When creating a wiki article, you should ensure that the subject only contains alpha-numeric characters, and those non-alphanumeric characters that are indicated as supported in the "Creating your own article" section of this document.
The link to a wiki article I created is showing as a new page:
- This can happen if you typed the wiki article's name incorrectly in the wiki markup for the link, or if the wiki article contains a none alpha-numeric character that isn't supported in the title.
Wiki markup is showing up in the short description of my wiki article from the views in the home page:
- If you did not include an abstract in your article, the wiki uses the first 300 characters of the wiki article as the abstract in the views. The views don't parse the wiki markup and displays it as text, so if you have wiki markup or HTML in the first 300 characters of an article that does not include an abstract, then the markup displays in the views. Ensure that you use the "Abstract" field to include a description of your article, or ensure that the first paragraph in your article does not include wiki markup. It's a good idea to include a short description of the article in the abstract field because this description enables readers to assess whether or not the article is what they are looking for without actually opening the article.
Tips for writing a great wiki article
You've always wanted to write a wiki article but thought, "I'm an engineer/administrator, not a writer, how can I get started and write something people want to read?"
Follow these simple rules and you'll be well on your way to becoming a star wiki contributor. It's good for our technical community and good for your career - there's no better way to pull together what you know than to teach someone else about it.
Pick a subject you know about
Your high school English teacher was right. Pick a subject you have real knowledge and expertise about. People read wiki articles to learn something they didn't know before and typically don't want to read a general article written by someone with the same general knowledge they have.
Keep it small
Don't write an article about Java. Write about something you could explain to a co-worker in 10 minutes, say, one specific way to generate a random number using Java.
Don't get side tracked
When writing your article on generating a random number don't get into a esoteric discussion of "what is random" or the history of methods of number generation. Stick to your main subject.
Write lots of drafts
Give your self some time to write a draft and don't be afraid to cut out parts that don't help explain your main subject. Show your article to a co-worker to get some feedback - you might even get a co-author in the process. Come back to it the next day and double check for typos or other errors before posting.
Use pictures and code samples if appropriate
If it helps support your article and makes it easier to understand, use screen shots or simple graphics. If your article is about coding, you might include a code snippet (just make sure it works). But don't feel you MUST use either if they don't really help your article. If you use code or provide a sample, try to make the directory structure match the default structure of the installed version of your product (e,g. the location of Java or the case of the folder names).
Keep it simple
Try to remember that co-worker you were explaining something to and don't use a formal stilted style. Keep your sentences clear and short. One way to keep ideas straight is to use bulleted lists to highlight main ideas. People understand things better when they are chopped into bite-sizes pieces, and it will help you keep your ideas organized when writing the article
Spell out acronyms
The first time you use an acronym, spell it out - for example: "Use of an LJO (Linked Java Object) is recommended for Java code that is more complex than....."
For more information
Provide links to other articles or to other sites that the reader could use to expand their knowledge of the subject you are explaining.
Use markup
Headings help keep the main ideas of your article organized. Use the wiki markup for headings as described above.
Code samples should be enclosed in the code markup to ensure that no characters in your sample are being translated by the parser. Refer to the wiki markup for code samples above.
Keep in contact
After you post your article, check back for comments and question and don't be afraid to answer the comments and edit your original article.
Get writing...
Keep your article light, brief, and full of information you're the expert on an you will have written a great article!
Tips for porting an MS Word doc to the wiki
TIP: Always author in the wiki so you don't have to port a Word document. But if you need to port a Word document to a wiki article, the information below can help make this transition smoother.
Save the Word document as HTML
Before you can port the document, save it as HTML. HTML files created by Microsoft Word carry a lot of extra information to make it possible to re-import the file into Word and save is as a .doc without losing certain features. The standard Save As dialog in Word is not primarily designed to create documents to upload to a Web server for anyone to browse.
- If using MS Office 2000, click File > Export As > Compact HTML. Office 2003 or later, Save as HTML.
- Download and run MS Office HTML Filter 2.0 This step gives you clean HTML.
Cleanup
Delete top Javascript and style sections at the top of the file, and then remove the following tags:
<div>
<span>
<ins cite>
<p> </p>
Table of Contents
The MS Word table of contents works because the HTML contains anchor links. However, you must replace the <p> tags with list tags if you want to show a hierarchical table of contents.
HTML with <p> tags in the table of contents:
HTML with <p> tags replaced with list tags.
Lists
Word uses tags and (non-breaking space) markup for ordered and unordered lists. The result is a sloppy list. Lists should be fixed up with list tags. For example:
Before:
After:
Links
Saving a Word document as HTML creates links with anchor tags:
<a href = “URL....”>URL</a>
Problem: This format shows up as two links on the wiki, and long URLS cause other text to be "carried" with it, thus creating non-breaking lines.
Solution: remove the <a href = “URL...”></a> and just show the URL.
Before:
After:
Or if the URL is very long, create a text link with the URL embedded:
[[URL|Linkname]]
Example: [[http://www.ibm.com|IBM]]
Displays as: IBM
Code samples
Use the code sample markup for all code samples. A width value no greater than 600 pixels is recommended because of non-breaking line issues.
Puts a scrollable box around the code sample. See code examples for details.
Images
When porting a Word document to HTML for the wiki, Word creates a subdirectory containing all your images as JPG and GIF files. You need to attach these images to the top of your wiki article. Click "Show attachments", then click the upload button to attach your images.
Note: keep the width of images under 600 pixels, otherwise you may have non-breaking lines
Use Wiki Creole markup
{{Image.jpg|alt text}}
{{Image.jpg|alt text|align="right"}}
Example:
{{directory.jpg|Person entry in LDAP directory}}
Browser support notes
It is recommended that you use the latest version of your chosen browser to interact with this wiki. For example, Internet Explorer 8, Firefox 3.6.x, and Google Chrome 6.0.x.
Known issues
This section contains a list of the known issues and common mistakes, and tips for working around them.
Viewing product documentation with Internet Explorer 7
When viewing product documentation using Internet Explorer 7, you might experience a the Web browser freezing for a long period of time, when you choose a documentation set from the navigation. We recommend that you use Internet Explorer 8, or another browser.
Word wrap issues
Large images (wider than say 800 pixels) and long non-breaking strings such as long URL links will "carry" other text along with it and cut off text on the right. In general an image should be no wider than 800 pixels.
If you run into this problem, decrease the width of images below 800 pixels and put long URLs into clickable text using an alias.
Use the code sample markup for all code samples. A width value no greater than 800 pixels is recommended because of non-breaking line issues.
Doing so puts a scrollable box around the code sample. See "Code examples" in this document for details. |