Wiki Instructions

From SWEBOK
Revision as of 18:29, 27 July 2015 by Daniel Robbins (Talk | contribs) (Paragraphs)

Jump to: navigation, search

This page contains instructions for how to utilize the wiki for the SWEBOK. In order to simplify maintenance, every attempt has been made to leverage standard wiki features when possible.

1 Document Structure

Each chapter of the SWEBOK should be stored on its own wiki page, entitled "Chapter X: Chapter Title Here". This page can be created by replacing all spaces with underscores in this suggested page title, and entering the URL "http://swebokwiki.org/Chapter_X:_Chapter_Title_Here". When the page loads, click on "Create" to create the new page. Note that page names are case-sensitive.

2 Headings, Table of Contents, Paragraphs

MediaWiki uses wikitext to define pages, which is a special text format that allows one to define paragraphs, headings, references, etc. Headings can be created using the following wikitext, which should appear on its own line, with no preceding spaces:


Top-level heading:

== My Title Here ==

Sub-heading:

=== My Title Here ===

Sub-sub-heading:

==== My Title Here ====

The first top-level heading that appears will be automatically numbered as Section 1 by MediaWiki. The first sub-heading appearing under this top-level heading will be labeled 1.1. MediaWiki will automatically construct a table of contents using these headings. Sub-sub-headings can be used but will not be numbered nor appear in the table of contents.

2.1 Paragraphs

Paragraphs can be stored in wikitext as successive lines of text that do not begin with any spaces. MediaWiki will combine these lines and display them as a single paragraph. To create a new paragraph, insert two blank lines within the wikitext. Sentences can span multiple lines. When converting paragraphs from the existing SWEBOK PDF, care must be taken to remove hyphenated words and replace them with non-hyphenated versions. It may be easier to use the source Microsoft Word document to copy and paste paragraphs, with hyphenation turned off.

All paragraphs will be indented automatically. In the SWEBOK, initial paragraphs in each section are not indented. The

{{{1}}}

template can be used to wrap the first paragraph in each section so that it is not indented. It is used as follows:
{{NoIndent|Your paragraph here.}}

2.2 Bold and Italic

To make text italic and bold, surround by two and three single parenthesis, respectively:

Rendered as ''italic''. Rendered as '''bold'''.

3 Pre-TOC Sections

In the SWEBOK, some chapters have paragraphs and sections that appear prior to the structured table of contents. To insert these sections, we will use a MediaWiki feature called a "template". In our case, we will use the IntroSection template, as follows:

{{IntroSection|title=Introduction|body=
The Software Requirements knowledge area (KA) 
is concerned with the elicitation, analysis, specification, and validation of software requirements
as well as the management of requirements during the whole life cycle of the software product.

It is widely acknowledged amongst researchers
and industry practitioners that software projects 
are critically vulnerable when the requirements-related activities are poorly performed.
Software requirements express the needs and
constraints placed on a software product that
contribute to the solution of some real-world
problem.}}

Templates begin with a {{ and end with a }}. Their first parameter is the template name, followed by a vertical bar, and parameters in variable=value format, with additional variable/value pairs delimited by a vertical bar. The IntroSection template allows sections to be inserted at the beginning of the chapter while preventing them from becoming a numbered TOC section. The template call above would render as follows:


Introduction

The Software Requirements knowledge area (KA) is concerned with the elicitation, analysis, specification, and validation of software requirements as well as the management of requirements during the whole life cycle of the software product.

It is widely acknowledged amongst researchers and industry practitioners that software projects are critically vulnerable when the requirements-related activities are poorly performed. Software requirements express the needs and constraints placed on a software product that contribute to the solution of some real-world problem.


4 Acronyms

Acronyms appear at the beginning of each chapter, and are specified using the {{Acronyms}} and {{Acronym}} templates, as follows:

{{Acronyms|
{{Acronym|name=GNU|description=GNU is not UNIX}}
{{Acronym|name=eSATA|description=external Serial ATA}}
}}

As you can see, the {{Acronyms}} template serves as a container for the other templates. Acronym definition lists should appear in the wikitext where they should normally appear in the flow of the document, typically at the very beginning of each chapter.