Skip to content

Commit

Permalink
chore: content fixes and README
Browse files Browse the repository at this point in the history
  • Loading branch information
@tlawrie
tlawrie committed Jun 14, 2024
1 parent 908a158 commit 3b31131
Show file tree
Hide file tree
Showing 9 changed files with 45 additions and 60 deletions.
52 changes: 17 additions & 35 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,12 @@ We welcome all our users to contribute to the documentation. While you can creat

## How to write content

1. Write documentation `.md` files in the `content` directory.
2. Add frontmatter for the `title` of the document. _See existing documents for reference._
1. Write documentation `.md` files in the appropriate content directory.
2. Add frontmatter for the document.

```file
---
title: What's New
order: 2
---
```

| Key | Type | Purpose | Required | Default Value |
| ----- | ------ | ------------------------------------------------------------------------------------------------- | -------- | ------------------------ |
| title | string | Used to build the link to document using kebabCase version of value. Used for sidenav navigation. | no | filename of the document |
| index | string | Specify where this doc should be shown in its category. | no | order in the folder |

**Note**
> Note: see existing documents for reference.
- If title is not provided, it will default to the filename of the document.
- If index is not provided, it will default to the order in the folder.
> Note: refer to the [Remix Docs Template](https://github.com/boomerang-io/remix-docs-template?tab=readme-ov-file#frontmatter) to understand the frontmatter requirements.
## Recommended Structure

Expand All @@ -36,34 +23,29 @@ If you are a solution team creating a new topic of content we recommend that you
The folder structure to match the above would be:

```file
content
|__ solution
|__ version
|__ introduction
|__ 00.overview.md
|__ 01.getting-started.md
|__ 02.whats-new.md
|__ 03.known-issues.md
solution
|__ introduction
|__ index.md
|__ overview.md
|__ getting-started.md
|__ whats-new.md
|__ known-issues.md
```

from here you can create additional topics such as architecture or detailed usage scenarios and information

```file
content
|__ solution
|__ version
|__ category
|__ document.md
solution
|__ category
|__ document.md
```

e.g.

```file
content
|__ boomerang
|__ 1.0.0
|__ architecture
|__ overview.md
flow
|__ architecture
|__ overview.md
```

## Content Configuration
Expand Down
8 changes: 6 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,15 @@ This repository contains the documentation Markdown source files for [useboomera

The `main` branch will be automatically accessible along with any releases.

## Releases

Releases are tagged with the version number matching a release and prefixed with the product. For example [email protected] or [email protected].

## Design

This Markdown metadata is used to generate the documentation site. The metadata is used to generate the table of contents, breadcrumbs, and other navigation elements.
Markdown metadata is used to generate the documentation site: table of contents, breadcrumbs, and other navigation elements.

This is based on the [Remix Docs Template](https://github.com/boomerang-io/remix-docs-template?tab=readme-ov-file#content) and its content requirements.
This is based on the [Remix Docs Template](https://github.com/boomerang-io/remix-docs-template?tab=readme-ov-file#frontmatter) and its content requirements.

## Contributing

Expand Down
6 changes: 3 additions & 3 deletions flow/architecture/application.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ _Notes:_
## Dependencies

| Dependency | Implementation | Notes |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --- |
| Kubernetes | <ul><li>Red Hat<sup>®</sup> OpenShift<sup>®</sup> Container Platform (4.2+)</li><li>IBM Cloud<sup>®</sup> Kubernetes Service</li><li>IBM Cloud Red Hat OpenShift Kubernetes Services</li><li>Microsoft Azure Kubernetes Service</li></ul> | Kubernetes 1.20+ | |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Kubernetes | <ul><li>Red Hat<sup>®</sup> OpenShift<sup>®</sup> Container Platform (4.2+)</li><li>IBM Cloud<sup>®</sup> Kubernetes Service</li><li>IBM Cloud Red Hat OpenShift Kubernetes Services</li><li>Microsoft Azure Kubernetes Service</li></ul> | Kubernetes 1.20+ |
| Tekton | TaskRuns | Part of Pipelines 0.23.3+ |
| Application Load Balancer | NGINX 0.23.0+ | |
| Database | MongoDB | |
| Message Streaming | NATS Jetstream 2.3.4 | Required if eventing is enabled |
| Certificate Manager | Jetstack Cert Manager (0.7.0) | Optional if you have your own TLS certificate as a Kubernetes secret |
| Logs | <ul><li>Kubernetes</li><li>Grafana Loki</li></ul> | If logging enabled, default is Kubernetes |
| Monitoring | New Relic Infrastructure, New Relic Kubernetes, New Relic APM Agent | If enabled |
| Tracing | Jaeger<sup>®</sup> | If enabled |
| Tracing | Jaeger<sup>®<sup> | If enabled |
16 changes: 8 additions & 8 deletions flow/fundamentals/parameters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,14 +85,14 @@ As this Task is a bring-your-own container, we have provided two mechanisms for

Boomerang Flow parameters are very similar to what you will find in Tekton<sup>®</sup> parameters and will be familiar to some of our users.

| Tekton | Example | Boomerang Flow | Example |
| ------ | ------- | -------------- | ----------------------------------------------------------- | ------ | ----------------------------------------------------------- |
| - | - | Global | `$(global.params.<parameter>)` or `$(params.<parameter>)` |
| - | - | Team | `$(global.params.<parameter>)` or `$(params.<parameter>)` |
| - | - | Pipeline | `$(params.<param name>)` |
| - | - | Workflow | `$(Workflow.params.<parameter>)` or `$(params.<parameter>)` |
| - | - | Context | `$(context.pipeline.name)` | System | `$(system.params.Workflow-name)` or `$(params.<parameter>)` |
| - | - | Task | `$(params.<param name>)` | Task | `$(params.<param name>)` |
| Tekton | Example | Boomerang Flow | Example |
| ------- | -------------------------- | -------------- | ----------------------------------------------------------- |
| - | - | Global | `$(global.params.<parameter>)` or `$(params.<parameter>)` |
| - | - | Team | `$(global.params.<parameter>)` or `$(params.<parameter>)` |
| - | - | Pipeline | `$(params.<param name>)` |
| - | - | Workflow | `$(Workflow.params.<parameter>)` or `$(params.<parameter>)` |
| Context | `$(context.pipeline.name)` | System | `$(system.params.Workflow-name)` or `$(params.<parameter>)` |
| Task | `$(params.<param name>)` | Task | `$(params.<param name>)` |

Reference:

Expand Down
2 changes: 1 addition & 1 deletion flow/fundamentals/schedules.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Allows you to define the cron schedule and timezone. The cron accepts both 5 par

Cron schedule syntax

```
```sh
# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of the month (1 - 31)
Expand Down
Loading

0 comments on commit 3b31131

Please sign in to comment.