gchq / gchq/sleeper

Improve configuration examples

Open
#7,277 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement parent-issue
Dominant language
Java
Stars
107
Forks
29
Avg merge
19h 46m
Merged PRs (30d)
141

Description

### User Story

As a user configuring Sleeper, I want the configuration format to be easy to work with and unintimidating, so that I can get started easily, and change the configuration I need to easily when it comes up.

### Description / Background

We'd like to make the example configuration files more useable.

### Technical Notes / Implementation Details

Currently the full example is very long and a bit intimidating, as the user wonders which properties they need to set.

Both examples set various properties chosen arbitrarily, so the user would need to remove those values to use these files as a base for their own configuration.

#### Example file generation

The template and example files are generated in GeneratePropertiesTemplates. The full example is in `examples/full`, and the basic example is in `examples/basic`.

#### Choosing/judging improvements

We can ask users whether our example files are helpful, and what they might change.

We can rely on our own judgment for what is important to include, and go property by property to decide whether it's important.

Users have raised some specific things in the past that we can look at in more detail.

#### Values that are set as separate parameters during deployment

Currently all the example and template files include all the mandatory values, including the instance ID, VPC and subnets. It seems a bit odd to put the ID, VPC and subnets in the configuration files, when these will be set at deployment time. When using the scripts you always need to pass them in explicitly. We could remove the need to include these in a configuration file set by the user at all, while still including them in the config bucket.

It might also be worth explaining explicitly in the property descriptions when they are usually set as deployment parameters rather than in the properties file. We can probably leave those ones out of the basic example.

#### Unexpected explicit values for properties

Some of the properties have values set in examples that the user would need to spot and remove, when they would expect them to be left as the defaults.

If we have a line setting each property to its default value but commented out, the user can easily take it and use it as a base. This is how most of the properties are shown already. We can ensure all of the properties are shown this way, rather than setting values explicitly that the user would need to spot and remove.

#### Values to include in the examples

The full example can include every property, but without any values set. This is similar to how the template files are now.

The basic example can include a subset of the properties that are each worth having the user look at, because it's more likely they'll want to set them. For example, it's likely the user will want to set the optional stacks property, rather than leave it as the default. We can triage all of the properties in the system to decide what should be included.

Contributor guide

Open the contributing guide

Research direction

Start with GeneratePropertiesTemplates and compare the generated examples in examples/full and examples/basic with the current templates. Review which properties are deployment parameters, defaults, or useful user choices, then update the generated examples accordingly. Done means the full example is comprehensive without unexplained explicit values and the basic example is a focused, usable subset.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.