DESOSA Markdown Style Guide

DESOSA Markdown Style Guide

We will use markdown that can be processed by

1. github for easy rendering
2. gitbook to create the on line book.

You can learn more about markdown in the official Gitbook documentation. Make sure to, at least, skim the documentation, as Gitbook has some peculiarities.

Images

• For your book chapter, create one folder “images-team-name” that is unique to your team and contains all images.

• Instead of relying on on line images, copy images to this local folder to ensure they stay there as the web evolves

• Double check image copy rights, and include appropriate attribution.

• Optionally crop out extra white space surrounding the image

• Use the standard markdown to include images, i.e.

    ![Optional ALT text](images-YOUR-PROJECT/image.png)
    *Your Caption Here*

Cross References

Unfortunately cross referencing and figure numbering are not supported by mark down.

The best way out is to resort to html anchors:

<div id="myfigure"/>
Your image here.

Then these anchors can be used for hyperlinking:

The main components are shown in Figure [Development View of XYZ](#myfigure).

Note that section titles automatically obtain a hyperlink, using the section title as id.

Citations

Markdown has no good support for citations.

For references to articles, I suggest the following:

• Add a section “References” at the end of your document
• Include a numbered list of references
• For each reference, provide full bibliographic information, such as authors, title, publisher, year, page number, URL, etc.
• Add an id for each reference, just like for images.
• Cite the reference by hyperlinking to that id, using the number for the reference as name.

Example

## Regular section
As explained by Rozanski and Woods [[1](#rw)], the context view is used for ...
In this chapter we extend the DESOSA line of work [[2](#desosa)] by ...

## References

1. <div id="rw"/>Nick Rozanski and Eoin Woods. Software Systems Architecture: Working with Stakeholders using Viewpoints and Perspectives. Addison-Wesley, 2012.
2. <div id="desosa"/>Arie van Deursen and Rogier Slag (eds). Delft Students on Software Architecture. http://delftswa.github.io, 2015.

This should result in the references shown at the end of this document with hyperlinked references such as [1] or [2].

Code

Do not use

<pre>
  <code>
    ...
  </code>
</pre

Instead use the markdown convention to start code with four spaces, since, e.g., PanDoc does not always treat such HTML well.

Section Structure

Make sure your top level title is at level 1, i.e., that it starts with a single #. All actual sections should then start at level 2, i.e., with ##.

Referencing GitHub user names

@[avandeursen](https://github.com/avandeursen)

Table of Contents

There is no need for adding a table of contents.

Example references

1. Nick Rozanski and Eoin Woods. Software Systems Architecture: Working with Stakeholders using Viewpoints and Perspectives. Addison-Wesley, 2012.

2. Arie van Deursen and Rogier Slag (eds). Delft Students on Software Architecture. http://delftswa.github.io, 2015.