The European Space Agency
Contact us

Documentation Portal

Overview

The APEx Documentation Portal enables projects to effortlessly create and host a documentation portal utilising the open source Quarto framework. Quarto is a comprehensive open-source system designed for scientific and technical documentation, using Markdown as the primary editing language and supporting the visualisation of both Jupyter and R notebooks. The proposed approach is complementary to hosting documents in PDF or Word format on the web portal. It offers significant advantages over these traditional formats, especially for technical writing with scientific plotting and code snippets. It also allows for introducing interactive elements in documentation. Projects that do not feel comfortable with an approach based on Markdown for editing and Git for versioning are still free to use those traditional formats.

Quarto generates fully customisable online documentation portals tailored for scientific publications, featuring interactive visualisations. It supports various scientific elements, including formulas, diagrams, and code. Additionally, Quarto can produce PDF or Word documents, making it ideal for scenarios where user documentation needs to be transformed into a project deliverable.

The content of the documentation portal is managed through either a new or existing GitHub repository. This allows portal managers and editors to edit the content in a well-known and familiar environment. Although some technical documents may be stored externally, Quarto enables referencing of these documents within the documentation portal. Additionally, thanks to the capabilities of GitHub, projects have the option to employ their own QA processes by leveraging branching, issues, and pull requests. Using GitHub Actions, the latest changes to the content will be automatically synchronised to the documentation portal.

Showcase Scenarios

A documentation portal can support several project scenarios, including:

  • User Manuals and Guides
    Develop and store user manuals and guides for any tools or software created during the project. This ensures that users can effectively utilise the provided tools.

  • Training and Onboarding
    Create and store training materials, tutorials, and onboarding guides for new team members or external visitors. This helps them quickly understand the project scope, tools, and processes.

  • Technical Project Documentation
    Maintain detailed technical documentation, including software code samples, algorithm descriptions, system architectures, and hardware specifications. This is essential for sharing technical information within the project.

  • Research and Analysis Documentation
    Document methodologies, analytical processes, and research findings. This helps ensure the reproducibility of results and provides a reference for future research.

  • Project Planning and Management
    Store project plans, timelines, milestones, and deliverables in the documentation portal. This keeps everyone informed about project progress and deadlines.

What does APEx offer

The APEx Documentation Portal Service provides users with a streamlined template to initiate their documentation process. As changes are made, advanced automation tools ensure that the documentation is published seamlessly to a location that integrates effortlessly within your project portal. This service is most effective when used in conjunction with the APEx Project Portal, maximizing the level of integration.

This documentation template includes the following features:

  • Initial setup of the Quarto framework
    We establish the Quarto framework within your GitHub repository, enabling a modern, flexible documentation structure.
  • Quality assurance tools
    The template incorporates quality assurance tooling to uphold the content standards of your documentation.
  • Automated build and hosting
    GitHub Actions are set up to automatically build and host your documentation website directly on GitHub, ensuring that updates are reflected promptly and efficiently.
  • Initial branding
    Initial branding of the documentation portal will be setup based on your project-specific guidelines.
  • (Optional) custom URL setup
    If desired, we can assist in setting up a custom URL for your documentation site, enhancing accessibility and branding.

What software is used under the hood

The APEx Documentation Portal utilizes the open-source Quarto software. To leverage this service, users should familiarize themselves with the basics of the Quarto system. Based on our experience, individuals who are comfortable with Markdown will find it straightforward to make basic edits. Furthermore, Quarto offers many advanced features that are well-documented and often simpler to use than their counterparts in traditional office tools. Notably, some features available in Quarto are not supported by standard office applications, making it a valuable resource for innovative documentation practices.

Examples

Table 1 showcases example projects that use the APEx Documentation Portal:

Table 1: APEx Documentation Portal - Project Examples
Stay Tuned

Additional information will be shared on this page as the project progresses.