Difference between revisions of "OOPM:Development:Documentation:HowTos:WikiDocuments"
| Line 91: | Line 91: | ||
{{Template:OOPM:Templates:Documentation:Shared:TBD|how to use and define templates}} | {{Template:OOPM:Templates:Documentation:Shared:TBD|how to use and define templates}} | ||
| − | |||
| − | |||
=== Special Documents === | === Special Documents === | ||
| Line 100: | Line 98: | ||
Glossary categories are considered to be sub documents that are part of a containing document. For example, for the requirements analysis | Glossary categories are considered to be sub documents that are part of a containing document. For example, for the requirements analysis | ||
we require a glossary section that is considered a part of the defining requirement analysis document in its given version. | we require a glossary section that is considered a part of the defining requirement analysis document in its given version. | ||
| + | |||
| + | [[Category:OOPM:Development:Documentation:HowTos|WikiDocument]] | ||
Latest revision as of 20:41, 8 May 2009
Contents
Documents in the Wiki
Introduction
For the purpose of documenting our software system, we will be using the MediaWiki.
MediaWiki provides a set of functions that will make documentation much easier.
- User defined Collections (aka Books)
- Templates
- Page Includes
TBD additional functions that make documentation easier
User Defined Collections
Whilst this is a rather handy feature, it also has a major shortcoming in that collections are either user property or communal property. No additional categories can be added to a collection so that it will be provided at the proper location in the hierarchy of pages in the OOPM wiki, for example the OOPM requirements analysis document must not be the sole property of a single user, as it is more or less a communal property, nor must it go into the global collections category page Category:Collections.
Therefore we will employ our own mechanism for authoring multi page documents, instead of using the existing collections feature, so that we keep the global MediaWiki:Collections namespace free from pollution and also for making sure that we will not risk losing valuable information in case that a user deletes his or her account and, by that also, the collections made (part) property of that user.
Besides, browsing the Category:Collections category is both out of context and also rather awkward for the user, especially when more collections become available over time.
See the section on multi page documents below that will provide you with the information required to author multi page documents for the OOPM wiki. Such multi page documents can also be versioned according to the rules set forth in the document OOPM:Documentation:HowTos:WikiVersioning.
Templates
TBD using templates and integration into the existing OOPM templates
Page Includes
TBD in order to include a page, one must use template usage notation, e.g. {{:OOPM:Documentation:HowTos:Versioning}}
Preview
Sample preview of an included article or fragment thereof
Multi Page Documents
As the MediaWiki based collections, see above, do not actually suffice our requirements, we will do the job of collecting the parts of our documents manually.
For this, we will be using multiple templates, with the Template:OOPM:Templates:Documentation:MultiPageDocument:1.0 representing our starting point for authoring multi page documents.
As was stated above, multi page documents can be seen as a collection of individual articles. Whereas each article itself can be represented by either a single page document or a multi page document.
Here is a sample multi page document that does not yet use the above mentioned template (taken from the article Help:Collections):
== Multi Page Document == ;Foo :[[First_article]] :[[Second_article]] :[[Third_article]] ;Bar :[[Fourth_article]] :[[Fifth_article]] :[[Sixth_article]] [[Category:FooBar]]
This will provide you with a document that will link to the different articles that are part of the multi page document.
In order to save us the layouting part, we will instead be using the above mentioned template. See the template for further usage details.
TBD integration of versioned articles, see OOPM:Documentation:HowTos:WikiVersioning
TBD integration of the existing Documentation/MasterToc template provided by the OOo wiki for inter-document navigation or a similar technique for adding navigation to our documents
Single Page Documents
TBD what are single page documents and when to use them
Page Includes
TBD how and when to use page includes
Templates
TBD how to use and define templates
Special Documents
Alphabetically ordered indexes a/o glossaries are always created as category pages in the wiki. That way we can easily associate individual entries with multiple such indexes a/o glossaries. Glossary categories are considered to be sub documents that are part of a containing document. For example, for the requirements analysis we require a glossary section that is considered a part of the defining requirement analysis document in its given version.
