Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Stardust/Formatting Guidelines

This page lists the formatting guidelines that should be used by all documents on the Stardust Wiki. The purpose of these guidelines is to create uniform experience to the readers.

Deciding on a new Page Location

A new page should be added under URL, Stardust/Knowledge_Base/Topic_Name/Nice_Page_Name_Underscores_for_Blanks
Where, topic can be any main item listed on knowledge base home page like Getting Started, Customization, Embedded Usage, Security. etc.

Please do not use spaces but underscores ( _ ) to create nice page names in natural writing. However, please also try to keep the name short. The page name will server as teh page title, no additonal title(repetition) should be used (would show up in TOC).

You may have sub-topics under main topic. For example, ‘SSO and Secure Communication with Stardust using Kerberos’ article is added at this relative URL;
Stardust/Knowledge_Base/Security/SSO/SSO_and_Secure_Communication_with_IPP_using_Kerberos.

If a deper hierarchy is used then overview pages listing sub items should exist on all levels. Otherwise the breadcrumbs on the top of the page will not display properly.


Adding a new Page

To add a new page in the knowledge base, do the following:       

  • from knowledge base home page, browse to the category under which you want to add a new page;
  • in the browser URL, append a forward slash (/) followed by the new page title. Use a well readable page location/title that uses "_" instead of blanks (!) and follows the "all nouns" capitalization rules. 
  • the wiki will display that there is currently no text in this page, and if you wish to edit and create a new page, you may click on ‘edit this page’ option; and
  • the wiki will open the page editor, and you may add content and save the page.


Page Titles, Headings and Capitalization

  • Use the "all nouns" style for titles and page headings: Capitalize all nouns and nouns only. Do not capitalize articles, prepositions, conjunctions, and forms of to be.
  • Do not repeat the title on the page but instead use a well readable page location/name that uses "_" as Blanks and follows the "all nouns" capitalization rules.
  • For all first class headings (level1) in your page, use the 'Heading 2' formatting.
  • For sub-headings under level1 heading, use 'Heading 4' and reduce headers down as per your need.
  • Note that by default all page headers appear in the table of contents section at the top. So if you want to highlight text in the page, use bold, italics or underline formating.
  • For normal paragraph text, use 'Normal' formatting option.
  • Do not prefix hedings with numerations. Those will be added automatically in the table of contents and adding them will double the numeration
  • Do not use dots or collons at the end of a title or heading


XML, SQL and Source Formating

Use the tag
<source lang="...">
to format XML, SQL or code snippets. The value of the ‘lang’ attribute can be either ‘Java’, SQL or ‘XML’.


Linking new Pages

When we add a new page at appropriate location in wiki, by default it is not linked with any existing page. We need to explicitly add a link to this new page on either knowledge base home page or under some topic overview page.

Use bullets with page titles on overview page to link pages.


Keywords

A Table of Contents is automatically generated at the top of an article. Add the keyword __NOTOC__ on the first line of the article using the Wikitext editor to suppress the ToC.
Edit links are automatically generated on the right side of header sections. To suppress them add __NOEDITSECTION__ at the top of the article using the Wikitext editor.

Hint: Technically these keywords can be anywhere on the page, but it makes sense to keep them at the top of the page, so they are easily found.


Run a Spellcheck

There are various plugins for different browsers that allow you to run a spellcheck on a website. Please use one of those or copy a preview of your wiki page into Word to run a spellcheck before submitting the page.

Back to the top