Skip to content

Commit

Permalink
Update README and hero content to enhance clarity on data contracts a…
Browse files Browse the repository at this point in the history 
…nd contribution guidelines
  • Loading branch information
gvdr committed Nov 14, 2024
1 parent 44cdea7 commit a7e2a64
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 74 deletions.
81 changes: 14 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,76 +1,23 @@
# Create your own blog now!
# Intro

Your blog will be generated by [marmite](https://rochacbruno.github.io/marmite/)
At PDH.Stat we take good care of all data we collect, process, and disseminate.

<details>
To be better at tracing provenance and ensuring data quality, we are experimenting with a new feature: data contracts.

<summary> Click to see screenshots </summary>
This are rather detailed, technical documents that map the flows of data from the source to the final products.
The contracts are negotiational, meaning that they are agreed upon by all parties involved in the data processing.
And they are living documents, meaning that they are updated as the data processing evolves.

**Light Mode**
![index-light](https://github.com/user-attachments/assets/ebb177a3-5c28-437f-88d2-2400474dd84c)
![post-light](https://github.com/user-attachments/assets/c4ea0485-efee-438a-82d1-1c8d9b31a3e8)
Not to reinvent the wheel, we adopted a recognised standard for data contracts specification, available [here](https://datacontract.com).

**Dark Mode**
![index-dark](https://github.com/user-attachments/assets/c72a9216-e553-4d91-b48e-7b1e913b264f)
![post-dark](https://github.com/user-attachments/assets/61e6aad9-d84d-4e12-9737-ece02ffd39d2)
## This repository

</details>
is where we store all data contracts for the data we process:
- the raw yaml files can be found in the `/contracts/` directory.
- this website also provides a user-friendly interface to browse and discover the contracts [here](https://pacificcommunity.github.io/pdh-dotstat-contract_explorer/).

---
## How to contribute

## Step 1

### As a Fork (recommended)

[CLICK ON FORK BUTTON](https://github.com/rochacbruno/blog/fork) and name your fork `blog`.

##### Or as a template

[Click on Use this template](https://github.com/new?template_name=blog&template_owner=rochacbruno&name=blog&description=Blog%20generated%20with%20Marmite) and name your new repo `blog`

## Step 2

Access https://github.com/YOURUSER/blog/actions and click the green button to enable actions.

## Step 3

Access https://github.com/YOURUSER/blog/settings/pages and set the
pages source to **Github Actions**

## Step 4

Then edit the `marmite.yaml` with your own information. (IMPORTANT! change the `url:..` field to match your own repo)

If you want to enable comments on the blog [read this](https://rochacbruno.github.io/marmite/enabling-comments.html)

## Step 5

Commit and see the Github Actions building a blog for you.

Your blog will be published at https://YOURUSER.github.io/blog

You can add add [custom domain](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) later

You can customize `css` on `custom.css`, `JS` on `custom.js` and custom themes and other customization options are explained on [customization page](https://rochacbruno.github.io/marmite/tag/customization.html)

---


## Building locally

```console
$ git clone git@github.com:YOURUSER/blog.git
$ cd blog
```

```console
$ cargo install marmite
```

```console
$ marmite . site
Site generated at: /site/
```

Learn more on [marmite](https://rochacbruno.github.io/marmite/)
If you are a data producer, data processor, or data user, you are welcome to contribute to the data contracts.

Actually, we encourage you to do so, as this will help us all to better understand the data we work with.
17 changes: 10 additions & 7 deletions content/_hero.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
tags: welcome, experiments
---

# Intro

At PDH.Stat we take good care of all data we collect, process, and disseminate.

To be better at tracing provenance and ensuring data quality, we are experimenting with a new feature: data contracts.
Expand All @@ -14,14 +12,19 @@ And they are living documents, meaning that they are updated as the data process

Not to reinvent the wheel, we adopted a recognised standard for data contracts specification, available [here](https://datacontract.com).

## This repository
## This website

is where we store all data contracts for the data we process:
- the raw yaml files can be found in the `/contracts/` directory.
- this website also provides a user-friendly interface to browse and discover the contracts [here](https://pacificcommunity.github.io/pdh-dotstat-contract_explorer/).
provides a user-friendly interface to browse and discover the contracts.

Use the search functionality (top left corner) to find the contract you are interested in.
Or explore them by tags, to see all contracts related to a specific topic.

## How to contribute

If you are a data producer, data processor, or data user, you are welcome to contribute to the data contracts.

Actually, we encourage you to do so, as this will help us all to better understand the data we work with.
Actually, we encourage you to do so, as this will help us all to better understand the data we work with.

This [github repository](https://github.com/PacificCommunity/pdh-dotstat-contract_explorer) is where we store all data contracts for the data we process:
- the raw yaml files can be found in the `/contracts/` directory.
- fork and drop a new file there, or get in touch with me at giuliodr@spc.int

0 comments on commit a7e2a64

Please sign in to comment.