Instructions to Authors, Reviewers, and Editors

Tags:

Instructions to Authors

• First and foremost, don't copy copyrighted works into this site. You can't just lift a paragraph or section of a document, or a drawing, out of something that someone else wrote and sign your name to it. You have to rewrite the text and add value to the content.
• A good paragraph is a minimum of three and a maximum of six sentences about a single topic. There are exceptions of course but the reader should be able to get the topic from the section header and stay focused on the topic for the short time it takes to read three to six sentences. If you have more material than six sentences, consider making more than one paragraph and focusing the topics for each.
• Write with the reader in mind. Try to think about the reader searching for answers as well as the topic you are presenting.
• Hyperlinks are powerful for the reader - cross link as many pages as possible and have a plan for links when writing a chapter (group of topical essays).
• Use templates when possible. Templates have XXX's where content should go. Search for the XXX's and eliminate them before turning it over to editors and reviewers to complete the topic. You can see a complete list of templates at TemplateHome.
• If a topic doesn't need a section in the template, just delete the unneeded template sections when you edit for other content.
• Don't make the editors and technical reviewers responsible for the authoring job. They will help improve your published work, but shouldn't have to clean up spelling, formatting, and incomplete topics.
• It is easy to introduce typos and spelling errors into the editing screen and they are hard to see if surrounded by lots of WikiWords and HTML code. There are two ways to protect against spelling errors. We suggest that you use both!
  • The Firefox web browser has a spell checker in it. Words not in the dictionary will be underlined in red as you edit. You can download the Firefox browser at http://www.mozilla.com/en-US/firefox/
  • Open MS-Word in a separate window. When you are finished with a topic, save it and then cut and paste the displayed text into the MS-Word window and run the spell and grammar check.
  • *Tip* - A note of caution when in a browser session or using multiple windows and using the browser back functionality; be sure that you are using and saving the most current page. Using the browser back functionality may bring back older incorrect versions of the page and overwrite your edits.

Style Conventions

• All heading levels should be in initcaps format (i.e., major words in capitals and minor words lower case).
• Technical writers use too many capital letters in the wrong way. Please do not capitalize a word just because it is important to the sentence or you want to emphasize it. You should capitalize proper nouns and Oracle has created a lot of proper nouns by naming many subjects of our writing. A proper noun is a name given uniquely to a person (e.g. James), place (Atlanta), event (the Super Bowl), group (the Oracle Applications User Group), organization (Oracle Corporation), position (the Database Administrator), etc. Since Oracle has created unique and specific names for so many business terms, the way you capitalize (or not) tells the reader when you are writing about the specific Oracle term or a generic business term. Before you capitalize make sure you are referring specifically to the Oracle proper noun and not a general reference. Examples of capitalization include:
  • The Oracle Applications are a suite of software applications used by businesses around the world. (i.e. Generic use of the term applications isn't capitalized.)
  • It took us 45 days to convert my company's general ledger to the Oracle General Ledger application. (i.e. application is not capitalized because it is not part of the Oracle name for the thing called Oracle General Ledger and the first use of the phrase "general ledger" doesn't refer to the specifically named thing called Oracle General Ledger)
  • The Key Accounting Flexfield can accommodate any chart of accounts structure. (i.e. chart of accounts is not capitalized)
  • We set up our fiscal year with 13 periods in the GL Calendar. (i.e. Calendar is capitalized because it refers to the specifically named Oracle Calendar object.)
  • Batches may contain many journal entries. (i.e. journal entries is not capitalized)
  • Each Accounting Attribute is associated with a Journal Header or Line. (i.e. The capitalized words are Oracle named things)
• If you use an acronym please use the full term with the abbreviation in parenthesis when the term is first used on the page (i.e. The Trading Community Architecture (TCA) is used by several applications.)
• List items should be in the same format (i.e., this list is all sentences with ending punctuation; other lists might just be sentence fragments starting with a verb or an outline format of topics or nouns). Lists with multiple levels can have different formats for different levels, but all of the items on a single level should have the same format/structure.
• Make sure your topic is attached to the right parent.
• Establish tags for your topic.
• Use icons and graphics to visually direct the eye to certain paragraphs that are especially useful to the reader.
• The word "application" should be capitalized when it is a proper noun as in Oracle Applications and "the GL Application." The word "application" should be in lower case when it is used generically as a synonym for module as in "the application has the following configuration step ...".

TIP: Open the topic "More formatting help" in a separate window when you are just learning to use the TWiki markup language and some of the extended capabilities beyond headings, bulleted lists, and tables. When in an editing window, click on "Show help" in the upper left hand corner. The "More formatting help"? link, at the bottom of the help screen, will open in a separate window.

Instructions to Editors

• If you see plagiarism, stop it and return it to the author to rewrite the topic.
• Please read the instructions to authors and reviewers also on this page.
• This is a checklist for editing a page that is almost ready for publishing.
  • Paragraph structure (Three to six sentences on a single topic? Topic of each paragraph easily identifiable?)
    • Break apart paragraphs that are too long, too complex, or have multiple subjects.
    • Flag one- and two-sentence paragraphs for further development or consolidation into a list.
  • Sentence structure (Are sentences simple, compound, too repetitive, etc.?)
  • Word choice (Words clearly understood by the reader? Simplify when possible.)
  • Readability (Easy for the reader visually and intellectually to scan and understand the page?)
  • Searchability (Does the topic fit in the topic hierarchy and master TOC?)
  • Links and tags (more links improve navigation and tags improve searching)
    • Link to a logical parent topic
    • Links to appropriate aunt and uncle topics (related topics of the parent)
    • Add or vote for tags
  • Formatting consistency (site standards)
    • Headers
    • Lists
    • Tables
    • Bullets
    • Use of icons and graphics (especially , )
  • Grammar, punctuation, and capitalization
  • Author credits
  • Final spell check

Instructions to Reviewers

• If you see plagiarism, stop it and return it to the author to rewrite the topic.

Comments

Links

• Related: GoodStyle, WikiWord, More formatting help

This Topic Is Referenced By These Topics:
Related Links: InformationAboutUs, PublishDocControlReport

Collaborating Authors and Reviewers: JimCrum