✏️ Contributing

Thank you for taking the time to contribute to the SKA SDP Pipelines Cookbook!

The cookbook is a work in progress and a collaborative effort across many teams. It is a way for us to share knowledge and improve the quality of the pipelines.

We welcome suggestions for improvements from anyone for any part of the documentation. This can include:

  • Fixing typos or grammatical errors

  • Clarifying confusing sections

  • Adding new tutorials, how-to guides, explanations, or reference materials

  • Updating outdated information

If you have any suggestions or feedback but don’t want to make changes yourself, please contact the maintainers of this repository and we will be happy to help. If you are on the SKAO Slack workspace, please also join the #proj-ska-sdp-pipelines-cookbook channel.

Follow the steps below to set up your local development environment and start making changes.

Prerequisites

Make sure you have the following installed on your local machine:

  • Git

  • Python 3.10 or higher

  • Poetry

If you wish, you can use the provided devcontainer for a fully configured development environment. This is recommended if you use Visual Studio Code. For more details please see devcontainer README.

Getting Started

  1. Clone the repository, including the make submodule:

git clone --recurse-submodules git@gitlab.com:ska-telescope/sdp/ska-sdp-docs.git

  1. Install the required dependencies using poetry:

poetry install

  1. Create a new branch for your changes

  2. Make your changes

  3. Format and lint your documentation using the make command:

make check

  1. Build the documentation locally to preview your changes

make docs

  1. Submit a merge request to the main branch

  2. Your changes will be reviewed and merged by the documentation team

Guidelines

We have structured the documentation following the Diátaxis framework, which includes four main types of documentation: Tutorials, How-to guides, Explanations, and Reference materials.

We have provided templates that you can copy and modify for your use case:

Make sure you add your new page to the relevant index file in the section (e.g., Tutorials index).

If you are adding a page to the Explanation section use the pages there as a guide for how to structure your page. Prefer the active voice and keep sentences short.

Use mermaid diagrams where they help to explain concepts (see Pipeline template for an example and refer to the mermaid docs for syntax reference).