\chapter{Introduction}
In all writing for publication, the writer's freedom of creation and expression are limited by a number of guidelines and specific regulations.
At best, a familiar set of regulations shared by reader and writer can create a kind of support network that allows the message to be relayed without distortion. It will be easier for readers to find
the pertinent contents in a piece of writing if its layout and structure are the same as they are used to. This also applies to writers. When writers follow a set presentation model,
they do not have to waste time on considerations that are secondary to the work itself, but they can concentrate on polishing the contents of the text. This means that it is a good
idea to practice following the rules for the layout, though you may think you know how to select a better way to present your work.
This is a guide for the layout and structure of theses and essays at the Department of Computer Science at the University of Helsinki. It is thus applicable to the course
Scientific Writing, the software engineering projects, seminars, and MSc theses. (This is an updated version of
the previous guide written by the course lecturers \citep{erkio01, erkiomakela96, erkio94, verkamo92}.)
The \LaTeX\ guide and \LaTeX\ style that has been published on the department's web site can be used as support for this guide.
\chapter{Structure}
Let us start by looking at the sections expected to be in a scientific text. Keep in mind that the same expectations go for all kinds of technical writing.
However, this document in itself, is not a scientific or a research
text, so there will be content lacks in terms of research question
setting in the introduction and evaluative material in the last sections.
\section{Abstract or summary}
%\enlargethispage{5mm}
The summary page contains the following elements: the bibliographical data of the work, an abstract, topic classification,
and the key words. The bibliographical data consists of title, name of the author, place of publication, date of publication, and number of pages.
The abstract should be short, generally one paragraph (100 words maximum) explaining the main contents of the work: topic, methodology and results.
Topics are classified according to the ACM Computing Classification System
(CCS). A small set of paths (1-3) should be used, starting from any top nodes
referred to bu the root term CCS leading to the leaf nodes. The elements
in the path are separated by right arrow, and emphasis of each element individually can be indicated
by the use of bold face for high importance or italics for intermediate
level. The combination of individual boldface terms may give the reader
additional insight.
\section{Introduction}
The purpose of the introduction is to introduce the goals of the work in general terms. Describe topic,
methodology and results (as in the abstract, but expand it).
In order to provide the reader a good starting point for
interpretations, it is good to start the introduction by
contextualisation of the challenges and solutions to be discussed. For
example, why a certain domain has a particular challenge and who are
intended to benefit from the solutions proposed.
The length of the introduction depends on the length of the whole work. A few pages of text does not need a
separate introduction, since it is an expanded summary in itself. The introduction to a 10-page text can
be 1--1.5 pages long. For a 50--70-page MSc thesis, a 2--4-page introduction seems reasonable.
The introduction should shortly describe the problem field of the whole work, the plot, and the conclusions,
in general terms. After reading it, the reader may decide whether to go deeper into the topic by reading the whole text.
\section{Topic chapters}
The nature of the matter at hand determines how the topic chapters are disposed.
In order to guide the reader, it is a good idea to start each main chapter with a short paragraph
on what the main topic of the chapter is and how it progresses from one sub-chapter to the
next. Especially relevant is to express how concepts, challenges,
solutions and research steps are bound together. There should be enough
guidance for the reader to allow expectation of the right storyline.
Basic rule for easy to follow text is to use the natural emphasis of the
text structure to support the content matter key concepts and thought
processes. This means using openings of sectiosn and text paragraphs for
key arguments and information moves, while the internal parts of
paragraps are filled with supporting aspects that those less familiar
with the topic area need. Those with better background knoweldge can
quickly skim trhough the text without loosing any essential arguments.
Each author has his or her personal ryhtm in the text, which is visible
for the reader as the length of text paragraphs and complexity of
thought chains within. A good policy is to take only one information
move or transition per paragraph. This way the text stays easy to follow.
Signs of problems with the disposition of the text are easily seen in texts
with only one sub-chapter, or with more than two chapter levels (main and sub-chapters). There may be justifiable reasons to use three-level
headings in some technical documents. Single sentence text paragraphs
are also to be avoided.
%\pagebreak
\section{Reference usage}
Relevant learning targets include superficial knowledge of several
citation styles and capability (and willingness) to follow a given
style and ordering of entires and bibliographical details in the list of references.
These aspects are essential as the approval of a PhD manuscript or
journal article may depend on them.
Disregard of which style you use,
references are always placed inside sentences. This means that e.g. a separate reference at the end of a paragraph would be inappropriate.
The structure of the text must clearly show what the reference relates to. At the same time, it
shows how long a piece of the text that the reference relates to.
Efficient positions for citations are right after the introduction
(definition) of a concept, a methods or such, or in the end of a claim
from the reference material. Furthermore, if quoting verbatime one must
use citation marks.
The text structures and wordings, in addition to the location of
ciations must clearly express whether claims or arguments are
authors' own, or if they come from the contribution of others. Thus is
is of bad style to open a section by listing the citations on which the
section is based on. Such method can further indicate more serious
problems like following reference material as it is instead of analysing
and synthetising material into new though processes.
\section{Conclusion}
At its simplest, a conclusion is merely a weak revision of the main points of the text. All more valuable
conclusion sections contain comments on e.g. the value of results, how the work relates to its environment, or
future visions. This kind of evaluations should be well-grounded in fact, though, or the conclusion
might inadvertently seem comical.
\section{Creating the list of references}
The following guidelines should be followed when creating lists of reference for the
assignments during the course Scientific Writing.
The guidelines are backed by two main goals: to make it as easy as possible to find the
referenced source, and to show what kind of evaluation process the referenced work has undergone. For these reasons
\begin{itemize}
\item the reference notes should always be so exact that the source can be recognized and found in catalogues and libraries
\item different types of sources (monographs, conferences, journals) have to be easy to distinguish from each other, and
\item the different parts of the list must conform to each other, especially for each source type.
\end{itemize}
Independent of the citation style in use,
the sources are listed alphabetically according to the author's name, and works by the same
author (group of authors) in the order in which they have been published. If some publication
does not have an individual writer, it is alphabetized according to its name.
The following information should be given on each source independent of
the citation style:
\begin{itemize}
\item
Name(s) of author(s) (surname, initial letters of first names) in the original order; if there are more
than three authors, we can write the name of the first author and {\em et al.} instead of the other names.
\item
the name of the publication or article in its original form
\item
place of publication:
\begin{itemize}
\item
of monographs: publisher, place of publication (can be omitted if the publisher is well known), year
\item
of journal articles: name of journal, volume, issue, year and month (in parenthesis)
\item
of articles from article collections (such as conference publications):
\begin{itemize}
\item name of collection, editor, publisher, place of publication and year
{\em or}
\item conference name, coordinator, place and time,
\end{itemize}
\item
of a report: series, report number, place, publisher and year
\item
of a web source: URL, validity date, possibly the date when referenced in square brackets
\end{itemize}
\item
page numbers, if the source is an article or constitutes a chapter in a compilation.
\end{itemize}
When using web sources, you should keep in mind that the threshold for publication on the web
is non-existent. It is better to concentrate on the publications of well-known scientific
publishers and the technical standards for which the web is the only publication channel. If
the same publication is available on paper, refer to that primarily and add the URL as a complement.
The list of references gives an example of a text that has been published through many
channels~\citep{abiteboul,dietinger}and another example that shows a standard that has
been disseminated only through the web~\citep{bray}. For web-based
references it is important to give both the publication date and the
time of reading and interpreting the material. The content is prone to
change, and dating your use, you protect your interpretations for
unnecessary accusations of being faulty, if it is known which version
you used.
The list of references for a text should list exactly the sources that the text refers to.
The list of references for this text is an example of how to present sources,
which is why it contains ''extra'' sources.
In any style,
put a full stop after the name of a publication or article, as well as after the bibliographical
data of each reference. Separate the other pieces of information with a comma. As is normal in
Finnish, only the first letter of the first word in the heading is capitalized, but in the titles of
conferences and compilations, each major word is capitalized (not articles or prepositions). See the
appended example for a model. For the sake of clarity, it is best to write {\em In the work} before
the name of a compilation, except in the case of conference publications where the name starts with
the abbreviation {\em Proc.} (for Proceedings). In such cases, no complement is necessary. You can
see the difference by comparing the layouts of the references ~''\citep{dantowsley90}'' and~''\citep{gannonetal89}'' .
In case of other citation styles, it is likely that you can trust the
results given by the automated reference management tools.
\chapter{Layout}
This chapter discusses the main issues of the technical presentation of a text.
\section{Disposition of text sections}
Each text should include a separate cover page, as in this model. The second page contains an
abstract, followed by a table of contents (on one or more pages), and then the main text.
Pagination starts on the first page of the main text (with the Arabic numeral 1). (Rigorous writers
leave out the number from the first page.) All the (numbered) headings and their page numbers should be
written into the table of contents. Many word-processing systems create the table of contents automatically
so that the writer does not have to worry about updating page numbers as the work progresses. If writers
wish to, they can paginate the table of contents and previous pages separately (with Roman numerals), e.g. like this model.
After the main text, but as part of the text body, comes the list of references; its heading is
not numbered. Any possible appendices are added after the list of references, with headings and internal page numbers.
%\enlargethispage{5mm}
If you want to make a coherent list of figures, algorithms and tables, this list should be placed i
mmediately after the table of contents. The value of such lists is a matter of opinion, so there
is no need to create one --- especially if your word-processing software does not support it --- unless your instructor explicitly asks for it.
If for some special reason you want to add an alphabetical index top your work, it should be placed after
the list of references and before appendices. An index should be noted in the table of contents, as s
hould the list of references (unnumbered chapter). Writers who want to create an index should use the automatic support their word-processing system offes.
\section{General text layout}
Nowadays you may plan your text to be printed on single side or double
side, with line spacing one, for the final copy.
For reviewing and feedback purposes, check with your readers for their
preferences. Most read and comment on paper and need some space for
marking.
For drafts you can use wide margins too.
Both margins should also be fairly broad (ca.~3~cm): the wider left margin is needed for binding the text and the
right one for the instructor's comments. Leave enough space (2--3~cm) at the top and bottom, as well.
The most effective way to distinguish features like chapters, figures, etc, is to have enough space
in your text. Separate paragraphs from each other with one and chapters with a few empty lines. If a
new chapter is about to start at the bottom of a page (with only one or two lines of text), it is better
to start it on the next page. However, it is not necessary to start every chapter on a new page, especially
not with a short text; if the text contains many pages that are nearly empty, readers might suspect that the
writer has tried to make it look longer than it is.
Any empty space may be utilized for displaying figures and tables. Especially if a text is written with the
same type of text throughout, empty lines are necessary for separating e.g.~text from tables. Empty space
is cheap, but adds to the clarity and readability of a text.
\section{Figures and tables}
%\enlargethispage{5mm}
All figures and tables should be placed as near the (first) place in the text that refers to them, but
not before this reference. The text should also explain what the writer wants to illustrate with the
figure. Figures can be interpreted in many different ways, so the reader needs guiding.
Figures should never be placed immediately under the heading of a chapter, but chapters should always
start with text. Figures should not be placed in the middle of a paragraph (much less a sentence), except
if the figure is placed at the top or bottom of a page and it is clear that the paragraph continues.
Figures do not always have to be placed immediately after the paragraph that refers to them. If there is
not enough space for a figure on the same page as the paragraph that refers to it, the rest of the page
should not remain empty, Though the figure is inserted on the following page. However, the figure should
never be more than one page away from the reference.
The image~\ref{kuvaesimerkki} shows how to present a figure. You must pay attention to the visibility of
figure parts and text, to the numbering of figures, and captions.
\begin{figure}[ht]
%\begin{figure}[tbh] t= top, b = bottom, h=here
\ \newline
\begin{center}
\includegraphics[width=0.9\textwidth]{kuvaesimerkki.pdf}
%\rotatebox{90}{\includegraphics[scale=.75]{kuvaesimerkki.pdf}}
\caption{Figure elements.}
\label{kuvaesimerkki}
\end{center}
\end{figure}
We must also pay attention to the size of figures. Any annotations must be clear and easy to read When
presenting performance curves, for example, the axels have to be named, the scale notated, and the units
clearly presented. If you present many things with similar figures, you should use the same scale for easy comparison.
The caption of a figure should be written underneath it, and it is preferable that it be short and to
the point than too explicit. The same goes for table captions.
Figures and tables should be numbered progressively. In long texts, two-level numbering should be
used (e.g. Figure 3.1) according to the chapter number, but in shorter texts, one-level numbering is good enough.
You should pay attention to presenting figure and table captions consistently, as well as to punctuation
marks. It is natural to put a full stop after a caption, since they are most often full sentences.
(The style for figure and table captions vary according to publisher and publication. The recommendations
at the Department of Computer Science also seems to vary with respect to where the caption should be placed.)
\section{Headings}
You can use a different font in headings than in the rest of the text, or underlining, larger fonts, or other
methods of emphasis, but generally it is preferred that you only use one of these methods, because if there are
very many font types and sizes, the layout looks messy. The format of headings must be consistent throughout
the text. You should not use any unnumbered ''extra'' headings.
\section{Using this model}
You can use this text as a model for the layout of your own assignment. The font types and sizes,
line spacing, etc vary according to word-processing system, so small deviations from the rule are acceptable.
The directive number of pages for written assignments given during the lectures for the Scientific-writing
course and in this guide are applicable to assignments with a layout like this guide's (font size 12 points). The
average line in this text should consist of about 80~characters and one page about 30~lines. The number of pages
includes the text itself and the list of references (the part paginated with Arabic numbers), not the
cover page, summary, or table of contents.
\chapter{Conclusion}
This text is a checklist for some of the rules governing written presentations, which you should
keep in mind when writing exercises and theses.
This collection of advise has been compiled by staff members as the
result of discussions on general good writing habbits in computer
science. The consensus is that all young researchers and academic degree
holders must be able to seek and follow instructions of layout and
structuring of texts depending on the contribution they are working on.
This set of instructions aims at unifying the looks of theses and other
study reports from the department, but it is also a representative of
the instruction sets students will meet later.
This set of instructions only address the looks of the document. Other
instructions must be sought, read and gained experience with in order to
learn to select the suitable semantical contents for the scientific texts.