Level: Introductory Kristin BiancoTest (newemail2@us.ibm.com), Job Title 2, 软通动力信息技术有限公司
02 Oct 2008 Your article abstract goes here. Put the main points and key phrases at the start of the abstract, because it will be truncated in search results. Aim for three to five sentences that express why the reader would care about the content (motive) and what h
Using the IBM developerWorks Word template
Welcome to the Microsoft Word template for creating developerWorks content. You can use this template as a basis for a new article, or use it to help you prepare existing content for submission to developerWorks.
Articles and tutorials are published on developerWorks in HTML format, but are generated from an XML (Extensible Markup Language) format. Prior to publication, the XML source of each article and tutorial is validated for acceptable markup as defined in the developerWorks XML schema and then transformed into the HTML for publication using an XSLT (Extensible Stylesheet Language for Transformations) stylesheet. This separation of article content from presentation details helps us use automated processes to manage our large site.
Your word processing document will be converted to our XML format before it can be published. This template provides examples of the things most commonly used in developerWorks articles and tutorials. Following the guidelines in this template will help you create content that will convert well. Remember the following key points.
-
Keep the layout of your article straightforward. Layout that is more complex than illustrated here is possible in a word processor, but will probably not convert well.
-
Apply styles for elements such as headings. Do not just change the font size or make it bold.
-
Use the toolbar to create bulleted and numbered lists. Do not enter your own numbers and format these with tabs.
The easiest way to create developerWorks content with this template is to follow these simple steps.
-
When you first opened the template you were prompted to fill in several fields. Once you have done this, save the template as a regular document (.doc). You can always update field values later, so don't worry if they aren't all correct yet.
-
Add your own content to this document so you can compare it to the content here, referring to these instructions as needed.
-
When you are ready to submit your work to your developerWorks editor, simply remove the instructions.
That's it!
If you are already familiar with using styles in a word processor, skip down to “Style use summary for developerWorks content.“ Otherwise, read this brief introduction.
Using styles
Styles are an important tool for organizing your document with a consistent appearance. Paragraph styles apply to a whole paragraph, except where they are overridden by character styles which apply to some text within the paragraph. Most of your text in Writer will probably be in the Normal style. If you use Writer, it will probably be in the Default style. To display the Styles and Formatting toolbar in Word, select Format, then select Styles and Formatting. The style at the cursor location is shown in the Styles and Formatting window. Within that window, you may select a different style by clicking on a style name from the list under the Pick formatting to apply heading as shown in Figure 1.
Figure 1. Applying the Heading 1 style.
If you have text already selected, then the style will be applied to it. If you do not have text selected, the style applies to text you type at the current insertion point.
Now that you know how to apply styles let's look at what styles are used in typical developerWorks content.
Major (and minor) headings
Major headings divide your article into logical pieces that we'll call major sections here. You create a major heading using the Heading 1 style, as for the heading above this paragraph. Click on the heading to see for yourself. The heading will appear in the left navigation area of the final article so users can easily move between major sections. It is a good idea to use short, succinct headings rather than long, verbose ones.
This template makes extensive use of major headings so you can easily jump around the HTML version of it if you'd like to use that for reference while creating your own work. You don't need to make your major sections this short; just use what is best for your content.
Within each major section you will have several paragraphs of content, perhaps including illustrations, tables and code listings. The style for paragraphs should be Normal in Word or Default in Writer. Variations, such as Body Text in Word work too. Usually whatever style your word processor opens with in a new empty document is a reasonable choice unless you've done some exotic customization of your word processor.
Minor headings
Long major sections can be broken into smaller subsections that we'll call minor sections, using second level headings. Create minor headings by applying the Heading 2 style, as for the heading above this paragraph. Click on the heading to check for yourself.
Minor headings help organize the content under major headings. Within minor sections you will use paragraphs of content, perhaps including illustrations, tables and code listing, as you did for major sections.
Lower level headings are used for figures, code listings, tables, and sidebars. We'll discuss those when we get to those elements.
Lists
You will often have lists in your article. These may be unordered (bulleted) or ordered (numbered).
-
After you select Bullets from the toolbar, you can start typing a bullet like this one. If you already had a couple of ordinary paragraphs selected, those paragraphs now become bulleted items.
-
Press enter at the end of each bulleted item to create a new bullet.
-
If you need some nested bullets like this one, you can use the right arrow (Increase Indent function), also on the toolbar, near the Bullets icon.
-
To return to the outer level, use the left arrow (Decrease Indent) or use Shift+Tab.
-
Perhaps you would like a few numbered items. Just create a new bullet item and then click the numbered list icon (Numbering) to switch from bullets to numbers.
-
Press enter to create another numbered item.
-
Any list can include code listings, tables, and figures (such as a screen shot within a numbered procedure).
When you are all done, click the Numbering icon again to return from numbering mode to plain text.
Character styles – bold, italic, and underline
The most common character styles (highlighting) you will use for developerWorks content are bold and italic.
-
Make bold text with the B (Bold) toolbar icon. Use bold for GUI controls such as the B here.
-
Make italic text with the I (italic) toolbar icon. You italics for book titles, or column or series titles
Do not use underlined text. Underline is used for hyperlinks in developerWorks articles. If your word processor document includes underlined text, or other unsupported effects such as color, strikethrough, engraved, or small capitals, among many others, these effects will be ignored or may cause problems with the conversion.
Refer to the section on highlighting conventions in our article “Authoring with the developerWorks XML templates“ for more information about recommended highlighting.
Code listings or preformatted text
Content on developerWorks often includes small snippets of code or a command within a sentence, or longer code listings that are two or more lines of code and set off from the rest of the text. You create inline code and code listings using Courier New or Courier font. For example, to run the program, enter runme.bat on the command line.
For listings, limit each line of code in your code listing to no more than 90 monospace characters (including spaces). For longer code lines, please find suitable places split the lines; long lines do not wrap automatically. Code lines longer than 90 monospace characters will eventually cause formatting errors that you will have to resolve with your editor, so use the ruler line below to check the lengths of your lines. To go to a new line and enter more code within a listing, use a “soft return” (CTRL+Enter) rather than a hard return (Enter). A user-entered hard return signals the text editor that you want a new paragraph, which is not the case within a code listing. In Writer and Word, you can verify that soft returns have been entered at the end of each line by looking for a small left-pointing arrow at the end of the line. To enable the display of arrows in a Word document, click Format in the tool bar, select Reveal Formatting, and then check Show all formatting marks under the Options heading.
Mark the paragraphs of code listing and set the font to Courier New or Courier.
Within code listings, you will probably find it convenient to set your font size down to about 8pt so the lines don't wrap with typical word processor margins. This has no effect on the font size used in the final HTML on developerWorks, but is an aid during your composition.
Indent your code lines as needed by using the space bar. And include a caption for your code listing; code listing captions use a Heading 3 style, as do figure, table, and sidebar captions.
Limit code listing length to no more than 100 lines. For a listing longer than 100 lines, divide it into smaller listings or excerpt the most important lines, and consider offering the entire code listing as a download. Your developerWorks editor can help you with these decisions.
Listing 1. Sample code listing at maximum width
|--------10--------20--------30--------40--------50--------60--------70--------80--------|
CODE LINE 1 HAS 90 CHARACTERS – YOUR LINES MUST BE NO LONGER THAN THIS 0000000000000000000
CODE LINE 2 – USING 8PT CODE HELPS LONG LINES FIT IN YOUR PAGE.
CODE LINE 3
CODE LINE 4
CODE LINE 5
CODE LINE 6
|
Code downloads
If you have downloadable code to go with your article, send it with your article draft to your editor.
Figures
Technical graphics such as screen captures, diagrams, and photographs enhance and help explain your content. To learn how to create and deliver graphics for developerWorks content, read "Illustrating your article or tutorial for developerWorks.”
Include a caption above the figure: figure captions use a Heading 3 style, as do code listing, table, and sidebar captions. Your graphics must be less than 572 pixels in width. Larger images will be resized by developerWorks graphics staff.
Figure 2. Caption for your figure
JBView.gif
Submitting figures
If you submit original images, indicate your image file name below the figure. When you submit your Word or Writer draft to your editor, attach any such figures for your article in an e-mail. You will be contacted by your editor if there are any image problems.
Tables
Use the Table toolbar icon or the Table main menu item to insert a table. Include a caption for your tables so you can easily reference them from other parts of your article. Table captions use a Heading 3 style, as do code listing, figure, and sidebar captions. Left-align the headings and data within your table columns unless you’re lining up numeric data with decimals. Keep your table simple. Tables with merged cells in rows or columns may not convert well.
Table 1. Caption for your table
|
Column 1 heading
|
Column 2 heading
|
Column 3 heading
| |
1234
|
ABCD
|
987.50
| |
5678
|
EFGH
|
10.62
|
Links
You can link to Web pages, such as the developerWorks main page, or to locations in this document, such as the Code listings heading. To link to a Web page in Word, select the words in your document that will comprise your link text, then use the toolbar icon for adding an Internet hyperlink. The Link to… field should be set to Existing File or Web Page. Enter the Internet address for the link target and ensure that the Text to display field contains the text you selected in your document. To link to another place within your document, the initial steps are similar. However, the Link to… field value should be Place in This Document. Once that is selected, you can select the heading that is to be the target of the link.
Figure 3. Creating a link to another web page
Figure 4. Creating a link to another location in the same document
Sidebars
Use a sidebar for a content detour or reinforcement. For example, you might define terms or provide a bit of historical background in a sidebar. Or you might summarize the key points of a lengthy discussion.
To create a sidebar in Word:
-
Click Insert, and select Text Box.
-
A “canvas” will appear, outlined with a gray border
-
Click once within the canvas and a small box will appear. This is the text box that will contain your sidebar text.
-
You may drag the borders of the text box to a size you think will accommodate your text.
-
Enter your sidebar text within the text box. The first line of text should be a heading; use the Heading 3 style.
-
Adjust the size of the text box as necessary. Then drag the borders of the containing canvas to match the borders of the text box such that the borders of the text box and its containing canvas overlap.
 |
Heading styles
Use Heading 1 for major sections
Use Heading 2 for minor sections
Use Heading 3 for figures, listings, tables, and sidebars.
Note that the default style for text in a frame is Frame contents. This is fine, or you can switch it to Default, if you prefer. |
|
The horizontal alignment of the sidebar in the Word document does not matter; there is no need to left- or right-align it. Your editor, along with the XSLT transformation, handles the positioning in the final HTML page.
Style use summary for developerWorks content
-
Headings.
-
Heading 1 for major sections
-
Heading 2 for minor sections
-
Heading 3 above the code listing, table, and figure for captions. Heading 3 also for sidebar headings
-
Body text should use a standard style such as Normal in Word or Default in writer.
-
Use the toolbar to create bullets and numbered lists. Use Tab or Shift+Tab to alter the nesting level (or in Word, you can use the left or right arrow icons in the toolbar).
-
Bold and italic are fine, but use the developerWorks highlighting conventions. Underlining, color and other font effects will be ignored.
-
Code listings use
Courier New or Courier font. Font size doesn't matter, but full width listings look better in your document at a reduced size such as 8pt. Each line in a code listing should be no more than 90 characters, including spaces.
-
Keep tables simple and use a bold font for heading lines. Use Heading 3 for the caption.
-
Things not mentioned here are likely to be omitted during conversion or cause conversion errors.
Resources
List any related links with URLs, along with explanations of their relevance, under a heading of Resources (use the Heading 1 style). Your developerWorks editor will reformat them in the developerWorks style. Here are a few useful examples that are relative to this document.
About the author | | | Testing adding a new bio 4 |
Rate this page
|