XML - Managing Data Exchange/Author guidelines

Editing Chapters

You simply click on the "edit this page" tab at the top of any page you want to edit. You can also just edit a section or subsection - any place you see a little 'edit' to the far right above a line, click on it to edit that section. The thoughts behind the editing process of the chapters will be documented in the "discussion" tab of each chapter - go there to record your intentions for your assigned chapter.

If you would like to make any suggestions to the editorial board, we welcome them. At the top of the XML: Managing Data Exchange contents page is a tab to "discussion" follow that link and edit the page with your comments, be sure to follow the directions for entries.

• Use wiki code, not HTML code when you edit a page.

• how to make a link : [[XML: Managing Data Exchange/NameOfThePage(on the page)|NameOfThePage(displayed as the link)]]

• no plagiarism : please use citations and references to books, articles, and websites that have helped you contribute to the book.

• All figures and graphics should be prefixed with 'xml' to avoid accidentally overwriting another file (e.g., xmldmcity defines the data model for city).

• Where possible use Portable Network Graphics (PNG) for graphics because of its superiority to GIF and JPEG. Also, PNG is Open Source. OpenOffice.org Draw can be used to create PNG files.

Consistency guidelines

- developed to create a consistent look and feel to the book

Layout

• Chapter summary required

The bottom of each chapter should include a chapter summary highlighting the key points of the chapter. Follow the formatting guideline detailed later on this page.

• Bold new words

As new concepts and terminology are introduced in each chapter, make sure that they are defined first before using them; so that the reader understands what the words and ideas represent. Bold the first occurrence of the word (or preceding the definition).

• Use the sentence format for titles

Capitalize the first letter of a title and allow the rest of the letters to be lower case, as in this title.

• Avoid the use of underline and all capital words

• Tables, figures, and code references

For consistency, label all tables, figures (e.g. charts and photos), and code examples as "exhibits." Place the label for exhibits at the top of the exhibit, flush left, and enumerate the exhibits, followed by a brief caption. Examples: "Exhibit 1: XML data types" and "Exhibit 2: Schema code example"

• Concept capsules and breathing room

Think of your chapter as a data model or a large steak. A useful data model is broken down into its smallest attributes that require recording and maintaining for future analysis. A large steak is best eaten in bite size pieces to prevent choking and promote good digestion. As you revise your chapter consider the basic elements of your topic; break your topic down and present each element in a section - so that it is easy for the reader to follow and understand each part. Feel free to use bullets to represent lists.

To continue with the steak analogy, it is also good to eat slowly, taking breaths between each bite. Allow for spaces between each subsection and greater spaces between each section. This opens up the text so that it does not appear to dense and compact - and therefore intimidating.

• NetBeans (or other XML editor) Examples

Scroll down the contents page to "Appendices". You will see a link to the chapter "Using an XML editor". When you open this link - go to the edit this page tab and insert a link under the NetBeans heading with the name of your chapter. This is the format for the link: [[XML: Managing Data Exchange/ChapterName(NetBeans)|ChapterName]] After you save your edit, the XML Editor page will contain a link to your new NetBeans page. It will appear red because no information has been posted to that page yet. Click on the link and paste all the NetBeans information from your chapter into the edit box. In your assigned chapter, at the places where there were NetBeans information (that you just cut and paste into the XML editor page) - put a link to the XML editor - your Chapter page.

• Help:Wikibooks <= this link will provide several wiki guidelines - this page is also accessible from the 'help' link in the navigation box on the left bar of every one of these Wikibook pages. It contains information on inserting pictures, creating tables using wiki language (which is much easier to write and read).

This help page also has a link to a "sandbox." This is a blank page that allows you to experiment with wiki without affecting a real page.

Code examples

• Make all code examples a uniform color (black)—some are all black; some are multicolored. Please change the ones that are multicolored to all black.

• HTML code is lower case.

• Keep the comments in the code, but put a space above and bellow each comment.

• Include the file name of the code in a comments tag. If you are the author of the code, include your name and the date you authored the code in the comments. See example:

    <!--
         Document   : city.xsd
         Created on : March 1, 2005
         Author     : Tim Jones
    -->

• Keep all the example codes in the chapter on the same topic—the TOURGUIDE. If there are examples in your chapter that deviate from this theme, please change them to show examples from TOURGUIDE.

• If your code contains HTML or the XML declaration then you will want to put the tags <pre> ... </pre>

• In order to get those 'pre' tags to show up I had to use the tags <nowiki> ... </nowiki>

If you run into trouble while inserting code, one of the two tags mentioned above might be able to get you out.

• You do not have to create a table around samples of a code example; usually just putting a few spaces in front of each line will create the dashed blue lined box

Spelling

• Use the spelling "stylesheet" instead of "style sheet."

• Use the spelling "opening tag" instead of "opening-tag."

• Check your wiki text with a spellchecker (e.g. copy and paste in a text editor that supports spell checking).

Exercises & Answers

Create two links at the bottom of your chapter, one to an Exercises page and one to the Answers page already made (you can find this answer page link at the bottom of the contents page).

In the Exercises page, cut and paste your chapter exercises into a new page. An easy way to create a new page is simply to go to your main chapter page, type "exercises" at the end of the URL, and hit enter. If the page does not exist, Wikipedia will ask you to create the page by going to "edit this page."

At the top and bottom of the Exercises page, provide a link to the chapter and the Answers page—and vice versa with the Answers page.

Elements of Style - Principles of Composition

taken from the Elements of Style - by William Strunk and E.B. White

• Make the paragraph the unit of composition - The subject will need to be broken down into topics, and topics will need to be broken down into concepts and subconcepts. Each concept should be explored within its own paragraph.

• Put statements in positive form - "Make definitive assertions. Avoid tame, hesitating, noncommittal language. Use the word 'not' as a means of denial or in antithesis, never as means of evasion."

• Use definite, specific, concrete language - "Prefer the specific to the general, the definite to the vague, the concrete to the abstract."

• Omit needless words - "A sentence should contain no unnecessary words, a paragraph no unnecessary sentences...Many expressions violate this principle: 'the fact that,' he is a man who ... - he ..."

• Avoid a succession of loose sentences

• Express coordinate ideas in similar form

• Keep related words together

• Place the emphatic words of a sentence at the end

Source code

For inserting source code (e.g., XML or Java) into the book, use the following format:

  <country>
      <code>au</code>
      <country>Australia</country>
      <flag>au.gif</flag>
  </country>

Use the following wiki code:

<pre><nowiki>
  <country>
      <code>au</code>
      <country>Australia</country>
      <flag>au.gif</flag>
  </country>
</nowiki></pre>

Section summary

Section summaries should appear in the following format:

A chapter summary

Use the following wiki code:

{| style="background:linen; border: 1px solid black; padding: 1em; width: 100%;"
|- 
| A chapter summary
|-
|}

Story

Stories/case studies should appear in the following format:

A story

Use the following wiki code:

{| style="background: lightyellow; border: 1px solid black; padding: 1em; width: 100%;"
|- 
| A story
|-
|}

References

• A guide to Wiki editing is online
• HTML tables can be converted to Wiki format using an online tool.