big revision

resmo · resmo · commit d86f9082f763 · 2025-12-25T14:42:29.000+01:00
diff --git a/Makefile b/Makefile
@@ -20,7 +20,7 @@ run:
 
 schema-doc:
 	wget -O ojobpub.json https://raw.githubusercontent.com/letsemploy/schema/refs/heads/main/v1/ojobpub.json
-	rm -f docs/implementation/ojobpub-schema.md
-	echo "---\nhide:\n- toc\n---" > docs/implementation/ojobpub-schema.md
-	jsonschema-markdown --no-footer --resolve ojobpub.json >> docs/implementation/ojobpub-schema.md
+	rm -f docs/ojobpub/schema.md
+	echo "---\nhide:\n- toc\n---" > docs/ojobpub/schema.md
+	jsonschema-markdown --no-footer --resolve ojobpub.json >> docs/ojobpub/schema.md
 	rm -f ojobpub.json
diff --git a/docs/implementation/quickstart.md b/docs/implementation/quickstart.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,16 +1,8 @@
 # About Let's Employ
 
-"Let's Employ" is an initiative with the following goals:
-
-Create a free, simple and convenient process to publish and find your vacancies on your own website. Make it simple and efficient for everyone to collect the data with help of a standardised job meta data format [_ojobpub.json_](./implementation/ojobpub-format.md).
-
-## Benfits
+Create a **free**, **simple**, **convenient** and **standardized** process to publish and find your vacancies on **your own website**. Make it **efficient** for everyone to collect the data with help of a standardised job meta data format [oJobPub](./ojobpub/index.md).
 
 - [x] **Simple**: Employers manage open job positions on their websites.
 - [x] **Efficient**: Search engines collect structured data from a known path on employers' web servers.
 - [x] **Keep Control**: Employers keep control of their data and application process.
 - [x] **Free**: No additional costs beyond what employers already pay for your domain and web hosting.
-
-## Modus Operandi
-
-![](static/nutshell.png)
diff --git a/docs/ojobpub/format.md b/docs/ojobpub/format.md
@@ -1,14 +1,12 @@
-# About oJobPub.json
+# oJobPub Format
 
-oJobPub is our minimalistic data file in JSON ([Wikipedia](https://en.wikipedia.org/wiki/JSON)), containing meta infos about your job openings.
+Below you find a sample, how a ojobpub.json might look like. This is really just one example and is neither exhaustive nor self-explanatory. An explanation of the fields can be found at [oJobPub JSON Schema](./schema.md).
 
-It must be placed in a defined path in your web hosting: `<yourdomain.tld>/.well-known/ojobpub.json`.
-
-## oJobPub Format
+!!! note
+    JSON might look complicated if you're not familiar with it, but don't worry — you won't have to write it by hand. Once this format is finalized, we'll provide tools to help you generate and validate the structure.
 
-In the following sample, we see first an `employer` object containing infos about the company: *name*, *location*, *industry*, (main website) *url*.
 
-Later we find a list of jobs. There is only one job in the sample but there is currently no limit how many job entries you add.
+## Sample
 
 ```json
 {
@@ -66,13 +64,7 @@ Later we find a list of jobs. There is only one job in the sample but there is c
 1. The `employer` json object with minimal information about the employer.
 2. The list of `jobs` objects with meta information about the job openings.
 
-
-!!! note
-    JSON might look complicated if you're not familiar with it, but don't worry — you won't have to write it by hand. Once this format is finalized, we'll provide tools to help you generate and validate the structure.
-
 Some of the (blue) keys (e.g. `workload` or `description`) are optional while others are required (e.g. `title`).
 
-This is why we provide a [oJobPub JSON Schema](ojobpub-schema.md) (also see [GitHub](https://github.com/letsemploy/schema)) and an online validator tool [validator.letsemploy.org](https://validator.letsemploy.org) to allow verification of the data structure.
-
 !!! tip
     While not all properties are required for a valid file, we highly recommend you fill out as much metadata as possible.
diff --git a/docs/ojobpub/index.md b/docs/ojobpub/index.md
@@ -0,0 +1,15 @@
+# About oJobPub
+
+oJobPub is the heart of our standard, our minimalistic data file in JSON ([Wikipedia](https://en.wikipedia.org/wiki/JSON)), containing meta infos about your job openings.
+It must be made accessible on a defined path in your web hosting, a so called _well-known path_ ([Wikipedia](https://en.wikipedia.org/wiki/Well-known_URI)).
+
+Example:
+
+**`<yourdomain.tld>/.well-known/ojobpub.json`**
+
+## Structure / Format
+
+The structure of the [format](./format.md) is defined in a [JSON Schema](./schema.md) ([json-schema.org](https://json-schema.org/understanding-json-schema/about))
+
+- Raw schema is located at [gh/letsemploy/schema](https://github.com/letsemploy/schema).
+- Online schema validation [validator.letsemploy.org](https://validator.letsemploy.org)
diff --git a/docs/ojobpub/schema.md b/docs/ojobpub/schema.md
@@ -4,7 +4,7 @@ hide:
 ---
 # oJobPub - Open Job Publishing Initiative
 
-Meta data format to publish open jobs on your website in a structured way. For the raw JSON Schema, visit [https://github.com/letsemploy/schema].
+Meta data format to publish open jobs on your website in a structured way.
 
 ### Type: `object`
 
diff --git a/docs/overview/approach.md b/docs/overview/approach.md
@@ -27,7 +27,7 @@ This lack of consistency and structure **makes it difficult for search engines**
 
 While we still **want to keep our content** on our own website rather than on commercial platforms that sell our data, the challenge is **making that content discoverable**.
 
-A simplistic, minimalistic, structured data file containing **meta information** about your job opening and a **link to your detailed job page** should be good enough! Welcome to [oJobPub](../implementation/ojobpub-format.md).
+A simplistic, minimalistic, structured data file containing **meta information** about your job opening and a **link to your detailed job page** should be good enough! Welcome to [oJobPub](../ojobpub/index.md).
 
 ## Predefined Location
 
@@ -37,7 +37,6 @@ Inspired by robots.txt or sitemap.xml, we place a meta data file _ojobpub.json_
 
 As a result, job openings can be indexed by **multiple search engines** without further efforts and without any additional cost as they are aware of the data's context.
 
-
 ## Keep the Control
 
 ![](../static/nutshell_3.png){ width="400"  align=right }
diff --git a/docs/overview/faq.md b/docs/overview/faq.md
diff --git a/docs/overview/how-it-works.md b/docs/overview/how-it-works.md
@@ -0,0 +1,4 @@
+
+## Modus Operandi
+
+![](/static/nutshell.png)
diff --git a/docs/overview/project.md b/docs/overview/project.md
diff --git a/docs/overview/why.md b/docs/overview/why.md
diff --git a/docs/quickstart/create.md b/docs/quickstart/create.md
@@ -0,0 +1,7 @@
+# Create the data format
+
+Create an [ojobpub.json](../ojobpub/index.md).
+
+We know, writing JSON manually is not fun. While we used a static ojobpub.json file to demonstrate the simplest way to provide the data, this endpoint is not limited to a static file. It could just as easily be served by a dynamic application or script. In fact, we are working on a tool which will allow to publish oJobPub like a breeze. But for the moment, it is up to you how to write it.
+
+To ensure your ojobpub.json's data is valid, we provide a [oJobPub JSON schema](https://github.com/letsemploy/schema) and a validator app [validator.letsemploy.org](https://validator.letsemploy.org) for manual validation.
diff --git a/docs/quickstart/index.md b/docs/quickstart/index.md
@@ -0,0 +1,9 @@
+# How to publish job openings
+
+There are a few easy steps:
+
+1. [Meet requirements](./requirements.md)
+2. [Create the data](./create.md)
+3. [Publish the data](./publish.md)
+4. [Let us know](./let-us-know.md)
+5. [Spread the word](./spread-the-word.md)
diff --git a/docs/quickstart/let-us-know.md b/docs/quickstart/let-us-know.md
@@ -0,0 +1,3 @@
+# Let us know
+
+Helps us to see, how things are growing. More on that later...
diff --git a/docs/quickstart/publish.md b/docs/quickstart/publish.md
@@ -0,0 +1,88 @@
+
+# Publish ojobpub.json
+
+ojobpub's data must be make accessible to a specific path `https://example.com/.well-known/ojobpub.json` (without `www.` prefix!, but read further about HTTP redirects)
+
+There are a few ways to make ojobpub.json accessible:
+
+- Local Path: Store it in your website root
+- HTTP Redirect
+- HTTP Reverse Proxy
+
+## Local Path
+
+Save the ojobpub.json on your webserver's root path by creating a directory `.well-known/` (not the dot prefix).
+
+The root path of your website might look like something like `/var/www/example.com/`, so the file _ojobpub.json_ would be placed in `/var/www/example.com/.well-known/ojobpub.json`.
+
+## HTTP Redirects
+
+Creating a redirect to a different domain, vHost or path.
+
+### Different vHost
+
+If you have a website under https://www.example.com you can try what happens if you place the ojobpub.json in this `vhost` so it would be accessible like so `https://www.example.com/.well-known/ojobpub.json`.
+
+Then access the location `https://example.com/.well-known/ojobpub.json` and see if it worked. Why? Many webservers are configured to redirect `example.com` to `www.example.com` while keeping the URI (path) per default.
+
+```
+$ curl -i https://example.com/.well-known/ojobpub.json
+HTTP/2 302
+location: https://www.example.com/.well-known/ojobpub.json
+server: Caddy
+content-length: 0
+date: Wed, 24 Dec 2025 10:59:51 GMT
+
+```
+
+### Different Domain
+
+You can redirect to another domain like `https://jobs.example.com/just-an example/ojobpub.json`.
+
+=== "Apache HTTPD"
+
+    ```
+    <VirtualHost *:443>
+      ServerName www.example.com
+      ServerAlias example.com
+
+      Redirect "/.well-known/ojobpub.json" "https://jobs.example.com/just-an-example/ojobpub.json"
+    </VirtualHost>
+    ```
+
+=== "Nginx"
+
+    ```
+    server {
+      server_name example.com www.example.com;
+
+      root /var/www/example.com/html;
+      index index.html;
+
+      location /.well-known/ojobpub.json {
+        return 307 https://jobs.example.com/just-an-example/ojobpub.json;
+      }
+
+      location / {
+        try_files $uri $uri/ =404;
+      }
+    }
+    ```
+
+=== "Caddy"
+
+    ```
+    example.com www.example.com {
+      route /.well-known/ojobpub.json {
+        redir https://jobs.example.com/just-an-example/ojobpub.json
+      }
+    }
+    ```
+
+## Reverse Proxy
+
+Reverse proxy is great to hide the final location from the public.
+
+If you have an application providing the data of ojobpub.json on the fly, we would recommend to use this option.
+
+Another sample would be to place ojobpub.json to an object storage (e.g. AWS S3) so a reverse proxy would access this bucket and serve the ojobpub.json.
diff --git a/docs/quickstart/requirements.md b/docs/quickstart/requirements.md
@@ -0,0 +1,13 @@
+# Requirements: Website and Domain
+
+You need **your own domain and website**: e.g. domain example.com.
+
+Publish your full description of your job openings in a web page (HTML) as one usually do. This can be using tools like a:
+
+- CMS (Wordpress, Drupal, etc.)
+- Static site generator (Hugo)
+- Plain HTML
+
+Important is, that the full job description is accessible using a hyper link, e.g. https://www.example.com/career/job-product-manager.html.
+
+This link will later be used in our data format.
diff --git a/docs/quickstart/spread-the-word.md b/docs/quickstart/spread-the-word.md
@@ -0,0 +1,14 @@
+# Spread the Word
+
+To gain popularity, it is essential that you spread the word. Let other know about it this effort by **adding a link** on your job site:
+
+[![Supports LetsEmploy.org](https://img.shields.io/badge/supports-LetsEmploy.org-purple)](https://letsemploy.org){:target="_blank"}
+
+```html
+<a href="https://letsemploy.org" target="_blank">
+  <img
+    alt="Supports LetsEmploy.org"
+    src="https://img.shields.io/badge/supports-LetsEmploy.org-purple"
+    />
+</a>
+```
diff --git a/mkdocs.yml b/mkdocs.yml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
++
 +## Modus Operandi
++
 +![](/static/nutshell.png)