Jump to: navigation, search

Difference between revisions of "Stardust/Formatting Guidelines"

m
Line 1: Line 1:
= Knowledge Base Formatting Guidelines =
+
= Knowledge Base 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.<br>
  
 +
== Deciding on a new Page Location  ==
  
This Stardust Knowledge Base Formatting Guide lists down the formatting guidelines that should be used by all documents on the Stardust knowledge base. The purpose of these guidelines is to create uniform experience to the readers.  
+
A new page should be added under URL, STP/Stardust/KnowledgeBase/&lt;topic&gt;/new_page<br>Where, topic can be any main item listed on knowledge base home page like Getting Started, Customization, Embedded Usage, or Security.  
  
<br>The guidelines are given below.<br>
+
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;<br>&nbsp;/STP/Stardust/KnowledgeBase/Security/SSO/SSO_and_Secure_Communication_with_IPP_using_Kerberos.  
  
== 1. Decide a new page location: ==
+
<br>
  
A new page should be added under URL, STP/Stardust/KnowledgeBase/&lt;topic&gt;/new_page<br>Where, topic can be any main item listed on knowledge base home page like Getting Started, Customization, Embedded Usage, or Security.
+
== Adding a new Page  ==
  
You may have sub-topics under main topic. For example, ‘SSO and Secure Communication with Stardust using Kerberos’ article is added at this URL;<br>http://wiki.eclipse.org/STP/Stardust/KnowledgeBase/Security/SSO/SSO_and_Secure_Communication_with_IPP_using_Kerberos.<br>
+
To add a new page in the knowledge base, do the following:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  
&nbsp;
+
*from knowledge base home page, browse to the category under which you want to add a new page;  
 +
*now, in browser URL, append a forward slash (/) followed by a new page title and hit the enter key;
 +
*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.
  
== 2. How to add new page? ==
+
<br>
  
To add a new page in the knowledge base, do the following:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+
== Page Titles, Headings and Capitalization  ==
  
*from knowledge base home page, browse to the category under which you want to add a new page;
+
*Use the "[http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles 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.
*now, in browser URL, append a forward slash (/) followed by a new page title and hit the enter key;
+
*If you wish to give a title to the page, use 'Heading 1' formatting.
*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
+
*For all first class headings (level1) in your page, use the 'Heading 2' formatting.
*the wiki will open the page editor, and you may add content and save the page.
+
*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.<br>
 +
*Do not prefix hedings with numerations. Those will be added automatically in the table of contents and adding them will double the numeration<br>
 +
*Do not use dots or collons at teh end of a title or heading
  
&nbsp;
+
<br>
  
== 3. Page headings: ==
+
== XML, SQL and Source Formating  ==
  
*If you wish to give a title to the page, use 'Heading 1' formatting.
+
Use the tag <source lang="XML"><source lang="..."></source> to formatting XML, SQL or code snipptes. The value of the ‘lang’ attribute can be either ‘Java’, SQL or ‘XML’.  
*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 index contents section at the top. So if you want to highlight text in the page, use bold or underline options.
+
*For normal paragraph text, use 'Normal' formatting option.<br>
+
  
== 4. Adding source code on the page: ==
+
<br>
  
Use tag ''&lt;source lang=""&gt; ''for formatting the source code. The value of ‘lang’ attribute can be either ‘Java’, SQL or ‘XML’.
+
== Linking new Pages  ==
  
== <br>5. Linking new pages.<br> ==
 
 
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.  
 
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.
+
Use bullets with page titles on overview page to link pages.&nbsp; &nbsp;
<br>
+
  
 +
<br>
  
 +
== Keywords<br>  ==
  
&nbsp;
+
A '''Table of Contents '''is automatically generated at the top of an article. Add '''''__NOTOC__&nbsp;'''''on the first line of the article (not using the Rich Editor) to suppress the ToC.<br>'''''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.<br>
  
&nbsp;
+
Keywords can be combined, just by putting them one after the other on the first line of the article.<br><br>

Revision as of 01:54, 11 November 2011

Knowledge Base 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, STP/Stardust/KnowledgeBase/<topic>/new_page
Where, topic can be any main item listed on knowledge base home page like Getting Started, Customization, Embedded Usage, or Security.

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;
 /STP/Stardust/KnowledgeBase/Security/SSO/SSO_and_Secure_Communication_with_IPP_using_Kerberos.


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;
  • now, in browser URL, append a forward slash (/) followed by a new page title and hit the enter key;
  • 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.
  • If you wish to give a title to the page, use 'Heading 1' formatting.
  • 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 teh end of a title or heading


XML, SQL and Source Formating

Use the tag
<source lang="...">
to formatting XML, SQL or code snipptes. 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  on the first line of the article (not using the Rich Editor) to suppress the ToC.
Edit links are automatically generated on the right side of header sections. To suppress them add at the top of the article using the Wikitext editor.

Keywords can be combined, just by putting them one after the other on the first line of the article.