Wiki Instructions
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.
Contents
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:
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:
- Chapter 1: Software Requirements
- Chapter 2: Software Design
- Chapter 3: Software Construction
- Chapter 4: Software Testing
- Chapter 5: Software Maintenance
- Chapter 6: Software Configuration Management
- Chapter 7: Software Engineering Management
- Chapter 8: Software Engineering Process
- Chapter 9: Software Engineering Models
- Chapter 10: Software Quality
- Chapter 11: Software Engineering Professional Practice
- Chapter 12: Software Engineering Economics
- Chapter 13: Computing Foundations
- Chapter 14: Mathematical Foundations
- Chapter 15: Engineering Foundations