extend the docs

Author: resmo

docs/faq.md

@@ -0,0 +1,15 @@
+## Why a new format? 
+
+There are already existing formats for job ads, the most promising of which [job-posting JSON Schema](https://schema.org/JobPosting) seems also be supported by Google [^1]. 
+
+However, a bot must crawl the entire website to find the job ads and it is bloated with data. For us, this format seems to be most useful for larger search bots such as Google. oJobPub does not restrict you from using this format on your job description website as well; it complements it.
+
+Another schema that is very similar to ours is [*json-job*](http://lukasz-madon.github.io/json-job/). It is somewhat more comprehensive, but the project has not been active for over 10 years. It does not define where this data should be placed on your website. We could have used it, but we didn't want to wake sleeping daemons.
+
+[^1]: [Google documentation about job-posting](https://developers.google.com/search/docs/appearance/structured-data/job-posting?hl=en) 
+
+## How can I help
+
+
+## How can I join
+

docs/how/index.md

@@ -6,6 +6,9 @@ You need **your own website**: e.g. www.example.com, on which you publish your j
 ## 2. Create a ojobpub.json
 Create file `/.well-known/ojobpub.json` (all lower case!) in a **specific JSON format containing structured meta information** about your job openings and link to the full job description on your website.
 
+!!! tip "file or application?"
+    We write about ojobpub.json to be a static file because it the simplest case, how to provide the data. But there is no limitation, that this endpoint could be an application or dynamic script to provide the data.
+
 ## 3. Validate
 
 To validate the JSON data format, we provide a [oJobPub JSON schema](https://github.com/ojobpub/schema) and an app [validator.ojobpub.org](https://validator.ojobpub.org) to help validate the data file.
@@ -18,12 +21,7 @@ This helps us to see, how things are growing. Once this format is known and etab
 
 ## 5. Spread the Word
 
-<<<<<<< Updated upstream
 Let others know you are publishing job openings using oJobPub by **adding a link** on your job site:
-=======
-Let others know you are publishing job openings using oJobPub by adding a link on your job site:
-
->>>>>>> Stashed changes
 ```html
 <a href="https://ojobpub.org">Supports oJobPub.org</a>
 ```

docs/how/ojobpub-format.md

@@ -1,5 +1,7 @@
 # oJobPub JSON Format
 
+oJobPub is meant to be minimalistic, mainly containing meta infos about the job and a short job description, a summary. It is not meant to have all possible data of a job posting: e.g. the process of application is and will not be covered.
+
 Before we go to oJobPub JSON, let's clearify two terms:
 
 - JSON
@@ -11,16 +13,19 @@ JSON (JavaScript Object Notation) is an open, lightweight, text-based data struc
 
 ## What is a JSON Schema
 
-[JSON Schema](https://json-schema.org) is an IETF standard providing a format for what JSON data is required for a given application and how to interact with it. Applying such standards for a JSON document enforce consistency and data validity,
+[JSON Schema](https://json-schema.org) is an IETF standard providing a format for what JSON data is required for a given application and how to interact with it: Applying such standards for a JSON document enforces consistency and data validity.
 
 ## oJobPub JSON
 
-oJobPub is meant to be minimalistic, mainly containing meta infos about the job and a short summary. It is not meant to have all possible data of a job posting: e.g. the process of application is and will not be covered.
+A possible output could look like the sample below, however, some of the (blue) keys (e.g. `workload` or `jobDescription`) are optional while others are required (e.g. `jobTitle`). This is why we also provide a [oJobPub JSON Schema](https://raw.githubusercontent.com/ojobpub/schema/refs/heads/main/v1/ojobpub.json) and an online validator tool [validator.ojobpub.org](https://validator.ojobpub.org) to allow verification of the data structure.
+
 
 !!! 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.
 
-An possible output could look like this, however, some of the (blue) keys (e.g. `workload` or `jobDescription`) are optional while others are required (e.g. `jobTitle`). This is why we also provide a [oJobPub JSON Schema](https://raw.githubusercontent.com/ojobpub/schema/refs/heads/main/v1/ojobpub.json) and an online validator tool [validator.ojobpub.org](https://validator.ojobpub.org) verify your written oJobPub JSON.
+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 open job positions, called *vacancies*. In the sample, we only see one vacancy but there is currently no limit how many vacancy entries you add. 
 
 ```json
 {

docs/index.md

@@ -4,8 +4,8 @@ oJobPub is an initiative with the goal, to create a simlified, optimized and eff
 
 ## Benfits
 
-- **Efficient**: Employers manage open job positions in one place.
-- **Optimized**: Search engines index structured data.
-- **Reliable**: Candidates find current job openings more reliable.
-- **In Control**: Employers keep control of their data and application process.
-- **No additional costs** beyond what employers already payed for domain and web hosting.
+- [x] **Efficient**: Employers manage open job positions in one place.
+- [x] **Optimized**: Search engines index structured data.
+- [x] **Reliable**: Candidates find current job openings more reliable.
+- [x] **In Control**: Employers keep control of their data and application process.
+- [x] **No additional costs** beyond what employers already payed for domain and web hosting.

docs/project.md

@@ -0,0 +1,34 @@
+# About the Project
+
+To establish a JSON schema as a standard format for publishing vacancies we follow the following strategy:
+
+## 1. **Define a Governance Model**
+
+First, we need to decide who will be in charge of maintaining the standard. This could be a non-profit organization, a consortium of industry players, or an open-source community. A clear governance model ensures the standard evolves transparently and in a way that benefits everyone.
+
+* **Create a Core Team:** Assemble a small group of stakeholders, including recruiters, developers, and job board operators, to guide the initial development.
+* **Establish a Decision-Making Process:** Determine how changes to the schema will be proposed, discussed, and approved. This could be a formal voting process or a consensus-based approach.
+
+## 2. **Build a Community**
+
+A standard is only useful if it's widely adopted. This requires active engagement with the community.
+
+* **Publish the Schema:** Make the schema publicly available on a platform like GitHub. Use a versioning system (e.g., `v1`, `v2`) to manage changes.
+* **Create Documentation:** Write clear and comprehensive documentation. Explain what each field is for, provide examples, and offer guidance on how to implement the schema.
+* **Launch a Website or Forum:** Create a dedicated space for discussion, bug reports, and feature requests. This is where you'll gather feedback and build momentum.
+* **Engage with Key Stakeholders:** Reach out to stakeholders. Show them the benefits of the standard and encourage them to participate.
+
+## 3. **Formalize the Standard**
+
+Once the schema is mature and has received sufficient community feedback, you can pursue formal recognition.
+
+* **Write a Specification:** Turn the schema and its documentation into a formal specification document. This should include a detailed description of every field, data types, and any business rules.
+
+## 4. **Promote Adoption and Provide Tools**
+
+Promotion is key to making the standard a success.
+
+* **Develop Client Libraries:** Create official libraries in popular programming languages (e.g., Python, JavaScript) to make it easy for developers to use the schema.
+* **Build Validation Tools:** Offer a free online tool where anyone can paste their JSON and validate it against the schema. This helps catch errors and encourages correct usage.
+* **Showcase Success Stories:** As companies start to adopt the standard, highlight their success. This provides social proof and demonstrates the real-world value of the format.
+* **Maintain and Iterate:** Continue to solicit feedback and release new versions of the schema as the industry evolves.

mkdocs.yml

@@ -1,13 +1,14 @@
 site_name: "oJobPub - Open Job Publishing Initiative"
 
 nav:
-  - About: index.md
+  - Intro: index.md
   - Why: why.md
   - Solution: solution.md
   - How:
     - Overview: how/index.md
     - ojobpub.json: how/ojobpub-format.md
   - FAQ: faq.md
+  - About: project.md
 
 theme:
   font: false
@@ -44,6 +45,10 @@ markdown_extensions:
   - pymdownx.details
   - admonition
   - attr_list
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - def_list
+  - footnotes
 
 plugins:
   - search