Add your comments directly to the page. Include links to any relevant research, data, or feedback.

Status	DONE
Impact	HIGH
Owner	Alessandro Domanico
Approver	Alessandro Fanna
Stakeholders	Alessandro Fanna Giulia Dall'Aglio Tiziana Titti
Informed
Due date	31 Mar 2019
Outcome	Asciidoc

Background

A very known problem of documentation is first all to produced it and the second it to keep it updated. Notoriusly devs don't like to document their feature and editors are not enough informed about changes happend in the code. For this reason there is often a problem of lack of documentation and/or outdated. Moreover, the whole documentation should alwasy be versioned across releases.

The ideal goal would be to find a way to achieve a strong link with the code, in a way that the developer developing a feature can easily "mark" where the doc is suscetible of change, so other people (or the dev him/herself) can subsequently revise and update them. Moreover, every change should be tracked and tagged with the correspondent code release version. Finally, each version (meant as collection of release tags) should be downloadable in a single PDF document.

Some tools that may be evaluated are:

Confluence itself: to see if the dev or the merger can mark any page via smart commits
Asciidoctor
LaTeX
MkDocs
Read the Docs

This decision involves:

OP-7 - Getting issue details... STATUS

OP-8 - Getting issue details... STATUS

OP-9 - Getting issue details... STATUS

Options considered

Option 1:

Option 2:

Option 3

Option 4

Option 5

Description

Confluence

Asciidoctor

LaTeX

MkDocs

Read the Docs

Pros and cons

Well Know

Well Structured

A bit slow

Maybe too much complex

Well Know

Very Powerfull

High Learning Curve

Estimated cost

MEDIUM

UNKNOWN

HIGH

UNKNOWN

UNKNOWN

Action items

Every solution should be studied individually, keeping in mind the overall process of development and also that people documenting can change over time like developers

Alessandro Domanico Evaluate Confluence
Alessandro Fanna Evaluate Asciidoctor
Alessandro Fanna Evaluate LaTeX
Evaluate MkDocs
Evaluate Read the Docs

Outcome

Browser not supported