Difference between revisions of "DocumentationGuidelines/WikiSingleSourcing"

From Eclipsepedia

Jump to: navigation, search
(Page Semantics)
 
(3 intermediate revisions by one user not shown)
Line 19: Line 19:
 
== Page Semantics ==
 
== Page Semantics ==
  
If converting to [http://www.docbook.org/ | DocBook] format from the wiki, the following conventions should be followed:
+
If converting to [http://www.docbook.org/ DocBook] format from the wiki, the following conventions should be followed:
  
{{note |Reference | This information based on information from [http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki Writing for DocBook Using the Wiki], from the Fedora Doc Project.}}
+
{{note |External Reference | This information based on information from [http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki Writing for DocBook Using the Wiki], from the Fedora Doc Project.}}
  
 
* One Wiki Page = One Chapter/Article
 
* One Wiki Page = One Chapter/Article
Line 28: Line 28:
 
When exporting using Mylyn WikiText, each page will become it's own DocBook XML file.  The recommended usage is:
 
When exporting using Mylyn WikiText, each page will become it's own DocBook XML file.  The recommended usage is:
  
    * One book = one parent file that calls in all prefaces, chapters, and appendixes
+
* One book = one parent file that calls in all prefaces, chapters, and appendixes
    * One chapter = one file
+
* One chapter = one file
    * One section = one <section> within a file
+
* One section = one <section> within a file
    * One article/tutorial = one file containing one or more sections  
+
* One article/tutorial = one file containing one or more sections  
  
 
To follow this example in the Wiki:
 
To follow this example in the Wiki:
  
    * One book = one parent Wiki page that is a Table of Contents of all the chapter pages
+
* One book = one parent Wiki page that is a Table of Contents of all the chapter pages
    * One chapter = one Wiki page, with one or more sections
+
* One chapter = one Wiki page, with one or more sections
    * One section = one part of a Wiki page marked by the = = , == ==, etc. around the title
+
* One section = one part of a Wiki page marked by the = = , == ==, etc. around the title
    * One article/tutorial = one Wiki page containing one or more sections.
+
* One article/tutorial = one Wiki page containing one or more sections.
 +
 
 +
{{note |Mylyn WikiText |Currently Mylyn WikiText does not follow this convention. It treates each page as a book, and the main headings as chapters, then all sub-headings as sections within the chapters.}}
  
 
== Watch Your Pages ==
 
== Watch Your Pages ==
Line 45: Line 47:
  
 
To ''Unwatch'' a page you are currently watching, select ''Unwatch'' from the sidebar on the wiki.
 
To ''Unwatch'' a page you are currently watching, select ''Unwatch'' from the sidebar on the wiki.
 +
 +
== Sections Need Content ==
 +
 +
If you have a section it needs to have content.
 +
 +
'''Wrong:'''
 +
<pre>
 +
= Section 1 =
 +
== Section 1.1 ==
 +
Section 1 needs to have conent
 +
</pre>
 +
 +
 +
'''Correct:'''
 +
<pre>
 +
= Section 1 =
 +
Some content that is relevant in section 1.
 +
 +
== Section 1.1. ==
 +
Some sub-section information that expands on topics introduced in section 1.
 +
</pre>
  
 
[[Category:Draft_Documentation]]
 
[[Category:Draft_Documentation]]
 
[[Category:Documentation Guidelines]]
 
[[Category:Documentation Guidelines]]

Latest revision as of 22:56, 16 August 2009

Warning2.png
Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.



Contents

[edit] Pages

[edit] Page Names

Wiki pages are typically of a upper camel case nature (SomePageName), however some tools can have problems with these names when converting them. At this time full page names (Some Page Name) are prefered, but not required.

If using standard wiki page names, make sure you put a full name equivalant when linking to it.

  [[SomePageName | Some Page Name]]

This should allow tools like Mylyn WikiText to generate the relevant links for the target platform.

[edit] Page Semantics

If converting to DocBook format from the wiki, the following conventions should be followed:

Note.png
External Reference
This information based on information from Writing for DocBook Using the Wiki, from the Fedora Doc Project.


  • One Wiki Page = One Chapter/Article


When exporting using Mylyn WikiText, each page will become it's own DocBook XML file. The recommended usage is:

  • One book = one parent file that calls in all prefaces, chapters, and appendixes
  • One chapter = one file
  • One section = one <section> within a file
  • One article/tutorial = one file containing one or more sections

To follow this example in the Wiki:

  • One book = one parent Wiki page that is a Table of Contents of all the chapter pages
  • One chapter = one Wiki page, with one or more sections
  • One section = one part of a Wiki page marked by the = = , == ==, etc. around the title
  • One article/tutorial = one Wiki page containing one or more sections.
Note.png
Mylyn WikiText
Currently Mylyn WikiText does not follow this convention. It treates each page as a book, and the main headings as chapters, then all sub-headings as sections within the chapters.


[edit] Watch Your Pages

If you are providing edits or maintaining a set of pages, make sure you use the Watch capability. This will inform you when updates or edits have been done to the page. To Watch your pages, select the Watch sidebar on the wiki.

To Unwatch a page you are currently watching, select Unwatch from the sidebar on the wiki.

[edit] Sections Need Content

If you have a section it needs to have content.

Wrong:

= Section 1 =
== Section 1.1 ==
Section 1 needs to have conent


Correct:

= Section 1 =
Some content that is relevant in section 1.

== Section 1.1. ==
Some sub-section information that expands on topics introduced in section 1.