Target release	2.0.0
Epic	SIITBX-37 - Getting issue details... STATUS
Document status	DRAFT
Document owner	Nicolas Ducoin (Unlicensed)
Designer	Nicolas Ducoin (Unlicensed)
Developers	Nicolas Ducoin (Unlicensed)
QA

Goals

The goal of "Online Help" is to provide documentation for the toolbox developers :

Modules developers should find information on how to develop new modules and access APIs in java native languages and other supported languages.
Toolbox developer should find information about the toolbox design to understand the architecture of the software and facilitate understanding of its internal working mechanisms.

Requirements

#	Title	Importance
1	It must provide a structured online help for developers	Must Have
2	It must be exportable to PDF and DOC format	Must Have
3	It should have index and search	Should Have
4	It should be integrated to the Sentinel ESA website	Should Have
5	It should make it be easy to add new content without specific knowledge of the technology chosen	Should Have
6	It might be generated automatically (html, pdf and doc)	Might Have
7	It might be exportable to SDD for S1, S2 and S3 toolboxes	Might Have
8	It might have chapters linked to requirements and issues in JIRA	Might Have

Possible technologies and tools

Sphinx

http://sphinx-doc.org/

From the web page:

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well. Of course, this site is also created from reStructuredText sources using Sphinx! The following features should be highlighted:

Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a language-specific module indices
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more

Pros:

Standard
Widely used
Looks good

Cons:

Only Python and C++ supported at the moment, a project exists for code in Java (https://bronto.github.io/javasphinx/#) but it still is very Python oriented, mainly for Python projects using Java.
No direct export to word
No link with requirements and issues

DocBook

From Wikipedia : DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software but it can be used for any other sort of documentation.

As a semantic language, DocBook enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, XHTML, EPUB, PDF, man pages, Web help[2] and HTML Help, without requiring users to make any changes to the source.

Pros:

Standard
XML format, with many editors and plugins for NetBeans, IntelliJ, etc.
Xslt processors for MS Word, html, pdf, etc.
Search with webhelp
Web pages and docs can be automatically generated

Cons:

New content added by developers only: adding new content needs a specific editor or an XML editor, does not seem “user friendly”.
Conversion from existing HTML pages not straightforward
Lots of work foreseen to have a nice output
No link with requirements and issues

Wiki

Many wiki exist, with pdf and word export plugins, like XWiki (plugins to export to word, pdf export directly supported) or DocuWiki (pdf export supported via plugin, no MS Work export).

Pros:

Easy to edit content
Easy setup
Possible to enable user comments
Might be available on ESA Sentinel Website

Cons

If not available on ESA Sentinel Website (or no proper export)
- New website will have to be setup and maintained
- Might not integrate on ESA Sentinel Website
Usually not easy to generate a nice structured document
no automatic generation

JIRA

Confluence JIRA gives the possibility to create technical documentation, with customisable PDF, XML and HTML export: https://confluence.atlassian.com/display/DOC/Developing+Technical+Documentation+on+Confluence+Wiki

Pros:

Create link with the requirements and issues
Customisable pdf and html export, with templates, possibilities to have a header, footer, first page, etc.

Cons:

Linked to JIRA
No automatic generation of documents

Other tools & technologies considered

Direct creation of web pages on the ESA Sentinel website, if it is possible and export is possible
JasperReport: Export to html, pdf and doc but mainly for reporting (graphics, tables, etc.)
Eclipse help: no direct export to pdf or word, and is built for applications, not online help
CMS like drupal have some export plugins. This however would require maintaining an other website, similar to Wikis.
Export from Office documents is possible, but the html export has limited functionalities (search, etc.) and generated html is not “clean” or can be hard to configure.

Conclusion

From the above analysis there are 3 main options:

Direct creation of web pages on the ESA Sentinel website, if customisable export to pdf and doc is possible. This would be the simplest solution, remains to see what is possible on the STEP website and how (and by whom) it can be updated (Wiki…).
DocBook is a standard and enables export to all wanted format but it will be time consuming to have a nice result, it is not “user friendly” and there will be no direct links with requirements in JIRA.
JIRA enables to create technical documentation. This documentation could be exported to html and pdf for STEP website. This has the advantage of having all documentation in one place and of linking requirements, specifications, design and issues. Furthermore it has nice export capabilities that could be extended.

Browser not supported