Newer
Older
# Documentation
To ensure the best documentation of our code we meet on a weekly base for a code sprint to document everything we have
coded throughout the week and haven't been able to document properly yet. The meeting takes place in the meeting room
at 1pm. Cookies may be provided.
## General Notions about Documentation
- Don't document a language's specifics, e.g. operators.\
*Example:* Use of `=>` in the XQuery expression `replace("qbc", "q", "b") => substring(1, 2)` MUST NOT be explained in
a comment.
- It is best to use a language's structure to document.
- Write the best documentation you can.
- Documentation and variable language is American English.
- Docs should be as close to the code as possible.\
This refers both to the documentation in a repository and in the code itself, e.g. inline documentation.
- Every code repository MUST have:
- a README.md file according to [this template](https://gist.github.com/PurpleBooth/109311bb0361f32d87a2) that
contains
- link to original repository (if the software is forked or otherwise based on preexisting software)
- short introduction on what the repository is about
- a guide how to get the software running (if makes sense)
- link to demo instance
- example or demo installation
- link to license file
- contribution guide
- link to style guide
- link to bug tracker/project management system
- known issues
- badges to CI status
- a LICENSE file
## Developer Documentation
### Software Architecture
Each software project should be documented using an architecture diagram that helps understanding its basic
functionality (even though using tools to generate diagrams such as UML class diagrams doesn't seem to be possible in
every case).\
*Examples:*
- [Generating call graphs in eXist-db](https://gitlab.gwdg.de/SADE/SADE/tree/develop/modules/callgraph)
Call diagrams can be useful to follow code and service calls and should be existing for every API method.
### API Documentation
- The docs should comprise used parameters, author and @since annotations
- [Example for Java](https://lab.sub.uni-goettingen.de/self-updating-docs.html)
- Links to callers must not be listed in the documentation, because this info will be deprecated soon.
It is strongly recommended to use call stacks of tools like Eclipse (Java) and/or Call Graph Module (SADE).
- Document REST-APIs using [OpenAPI](https://github.com/OAI/OpenAPI-Specification) if possible.
OpenAPI doc should be located at `/doc/api` on servers.
We currently use OpenAPI for RESTXQ and JAX-RS service endpoints.
#### OpenAPI for RESTXQ
For documenting RESTXQ APIs in our eXist-db systems we use the [OpenAPI4RESTXQ](https://gitlab.gwdg.de/subugoe/openapi4restxq) application.
It simply has to be installed in eXist-db and configured according to the [instructions](https://gitlab.gwdg.de/subugoe/openapi4restxq#use).
#### OpenAPI for CXF Java JAXRS Applications
We have not yet finished the OpenAPI documentation of our Java services, but a few tests with the [OpenAPI Feature of Apache CXF](https://cxf.apache.org/docs/openapifeature.html) have already been implemented.
The outcome of this OpenAPI documentation shall be the automated generation of API doc, to be written directly IN THE CODE as Java Annotation, using the @Operation annotation, see [example](https://github.com/apache/cxf/blob/master/distribution/src/main/release/samples/jax_rs/description_openapi_v3_spring/src/main/java/demo/jaxrs/openapi/server/Sample.java#L65) and then to be read and directly be used from within a HTML page.
An automatic generation of a [OpenAPI JSON file](https://dev.textgridlab.org/1.0/tgsearch-public/info/openapi.json) should be possible to use it with a [Swagger UI HTML page frontend](https://dev.textgridlab.org/1.0/tgsearch-public/info/api-docs/?url=/1.0/tgsearch-public/info/openapi.json).
We can deliver that page with every service or we could deploy a central Swagger UI service for all the documentation.
For every service endpoint an OpenAPI doc could be provided, such as already done for [TG-search](https://dev.textgridlab.org/1.0/tgsearch-public).
We also can combine this OpenAPI doc with our existing Sphinx API documentation (such as the [TG-search Sphinx API documentation](https://textgridlab.org/doc/services/submodules/tg-search/docs/index.html) as you can find [here](https://sphinxcontrib-openapi.readthedocs.io)).
### CESSDA's Software Maturity Levels in RDD (CA1.3)
`MUST` be SML2, which is defined as follows:
> There is external documentation that describes public API functionality and is sufficient to be used by an
experienced developer. If available, source code is consistently and clearly commented. Source code naming conventions
are adhered to and consistent.
#### Actions to Be Taken in RDD
- provide a fully documented public API, e.g. by using OpenAPI
- naming conventions still have to be discussed --> style guide?
- reference to style guide used in the CONTRIBUTING/README file?
## Admin Documentation
- The docs should comprise how to install the software, how to run and/or restart it, how to test the installation,
...
### CESSDA's Software Maturity Levels in RDD (CA1.2)
`MUST` be SML3, which is defined as follows:
> There is a deployment and configuration manual that can guide an experienced operational user through deployment,
management and configuration of the software. Exception and failure messages are explained, but descriptions of
solutions are not available. Documentation is consistent with current version of the software.
#### Actions to Be Taken in RDD
- deployment: short deployment descriptions can be provided in the README, more detailed explanations should be kept
separately (such as INSTALL(.md), linked from README)
- exception and failure messages are described in doc strings/function annotations
- function documentation should be generated automatically and made available/searchable in the web (such as
readthedocs, javadoc html, etc. pp.)
## Server Documentation
This type of documentation is provided and maintained in our DARIAH wiki space.\
We have a template encompassing all information necessary: To create a wiki page for a new server navigate to the FE
Server list, select "..." right beside the "Create" button and search for "FE-Server".
## User Documentation
This may encompass:
- how to use the software and APIs, FAQs, walkthroughs, ...
- guided tour (Bootstrap Tour) as user documentation
- for SADE portal usage (such as Fontane, BdN, Architrave)
- for complex Digital Editions
- screencasts
### CESSDA's Software Maturity Levels in RDD (CA1.1)
`MUST` be SML2, which is defined as follows:
> There is external documentation that is accessible and sufficient for an expert user to configure and use the
software for the user’s individual needs. Terminology and methodology is not explained.
#### Actions to Be Taken in RDD
- a README(.md) has to be available in the source code repository (cf. [General Notions about
Documentation](#general-notions-about-documentation))
`SHOULD` be SML3, which is defined as follows:
> There is a user manual that can guide a reasonably skilled user through use and customisation of the software to the
user’s individual requirements. Documentation is consistent with current version of the software.
#### Actions to Be Taken in RDD
- a more detailed explanation is available for the user at some place (such as user guide in wikis, etc. pp.)
- docs should also be provided in a `docs` directory in the source code repository
- docs are revised regularly during our doc sprints