Wiki Instructions

From SWEBOK
Revision as of 20:20, 28 July 2015 by Daniel Robbins (Talk | contribs) (Headings, Table of Contents, Paragraphs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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, and customize them as needed to reflect the general document structure and formatting of the printed SWEBOK.

1 Document Structure

Each chapter of the SWEBOK should be stored on its own wiki page, entitled "Chapter X: Chapter Title Here". These page links are listed at the end of this page.

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 {{NoIndent}} template can be used to wrap the first paragraph in each section so that it is not indented. You can view the wikitext of this paragraph or the following example to see how it is used:

{{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 Post-TOC Sections

All chapters have post-TOC sections that are not numbered. Similarly to the IntroSection template, there is a EndSection template which works identically and can be used to create sections of text (like References and Further Readings) that appear as unindexed sections after the main TOC.

To see these sections in use, see the Test chapter wiki page, and click "Edit" or "View Source" to see the corresponding wikitext.

5 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.

6 Defining References

References are defined in an {{EndSection}} template at the end of each chapter page, which has a basic structure as follows:

{{EndSection|title=References|body=
{{reference
|number=1
...(more text here)...
}}{{reference
|number=2
...(more text here)...
}}{{ReferenceList}}
}}

Since this is a somewhat complex set of nested template calls, let's take a look at how these templates work together. The outermost template is an {{EndSection}} template, which creates a section at the end of the document that is not listed in the TOC. The body of this template is one or more {{Reference}} templates, which are used to store the reference data, but do not display anything on the page. Then, following the list of references, the {{ReferenceList}} template appears, which will display a list of references in order.

Individual references use the following format, which can be viewed by viewing the Template:Reference page:

{{reference
|number=
|author=
|article=
|publication=
|edition=
|publisher=
|issue=
|date=
|part=
|link=
}}

Above, the number parameter is used to specify the number associated with the reference in this chapter. Most other parameters should be self-explanatory. The issue parameter is used to specify an issue number of a journal or magazine, while the part parameter is used to specify a list of pages or sections in a publication. The link parameter is used to specify a hyperlink in http:// format when referencing an online resource.

7 Citing References

To refer to a reference in inline text, use the {{referenceLink}} template, which takes two parameters: number and parts. You can view an example of its use within paragraph text in the "Further Readings" section of the Test chapter.

Many sections of the SWEBOK have a list of references at the top of each section. These lists can be created using the following set of templates:

{{RightSection|{{referenceLink|number=1|parts=c4, c4s1, c10s1, c10s4}}}}

You can view an example of this in the "Subsection" section of the Test wiki page. Multiple references can be listed as follows:

{{RightSection|{{referenceLink|number=1|parts=c4, c4s1, c10s1, c10s4}} {{referenceLink|number=2}} {{referenceLink|number=3|parts=c1}}}}

Simply separate each {{referenceLink}} template call by a space.

8 Chapter Structure

For the purposes of translating the SWEBOK to wikitext, it is best to focus on the content sections for now. Using the guidelines in this page, and the Test chapter page as an example, the converted wikitext for each chapter can be stored on the following pages: