changes based on jtbx's review

A single sentence per line

README.md

@@ -29,25 +29,57 @@ To populate the calendar data, please run `./fetch-calendar.sh` before running h
 Running the hugo command without and parameters will re-generate the site in the `public` directory.
 To deploy the website, just copy the whole folder to a directory which is servered by the webserver of your preference.
 
-Please note, that the website should be re-deployed at least daily to update the "announcement" section on the front page even if there were no changed to the content.
+Please note that the website should be re-deployed at least daily to update the "announcement" section on the front page even if there were no changed to the content.
 
-### Add Pages
+### Previewing Changes Locally
 
 To run a local version, just install HUGO by following the [instructions](https://gohugo.io/installation/) for your operating system.
 To build the website and run a development webserver, execute:
 ```shell
-hugo server
+hugo server --buildFuture --buildDrafts
 ```
 
-To also build posts in the future or in draft state, run this instead:
+Note: the flags `--buildFuture --buildDrafts` makes Hugo process all content, even if the `publishDate` is still in the future, or the content is marked as `draft: true` in the frontmatter. You usually want these flags, especially if you are preparing content that should only be shown after a certain date.
+
+Also see [Submitting Your Content](#submitting-your-content) below.
+
+### Adding Content
+
+There are two basic types of posts: Events and blog posts.
+Hugo and the template set distinguish between these two types based on frontmatter information.
+When manually creating content, you need to take extra care to use the correct frontmatter data.
+See the link to the Hugo archetypes below for details.
+
+**If at all possible, use `hugo new content` with the appropriate parameters to create the new content file correctly.**
+
+You should always set these frontmatter fields:
+* `categories`: must be either `article` or `event`; see below.
+* `date`: the date displayed for this content.
+  For events, that should be when the event takes place; for blog posts, it is when the post was written.
+* `publishDate`: the date and time the content should be published.
+  Note that if you do not specify a `publishDate`, the value of `date` will be used.
+* `title`: the headline of your content.
+
+#### Add a Blog Entry
+
+Blog posts (the archetype is called `article`) should be used for information that will be relevant for a longer period, for example explanations about technical, political or cultural topics.
+Articles will be shown for a few days on the home page. The [blog page](https://hamburg.ccc.de/blog/) shows all posts, newest first.
+In addition, the `tags:` can be used to find blog posts about certain topics.
+
+To create a new general blog post, run a command like this:
 ```shell
-hugo server -D
+hugo new content --kind article blog/yyyy/yyyy-mm-dd-your-article-title/index.md
 ```
 
+If you want to create a blog post from scratch, or convert an event into a blog post, see the frontmatter data in [themes/ccchh/archetypes/article.md](themes/ccchh/archetypes/article.md).
+In particular, you need to set `categories: article`.
+You do not need to specify an explicit `publishDate`, as the value of `date` will be used as a fallback.
+
 #### Add an Event Announcement
 
-There are two basic types of posts: Events and articles.
+Events will be shown on the home page from the frontmatter `publishDate:` until the `date:` (plus a few hours grace period).
-Events will be shown on the home page from their publishing date until they have happened and shall be used for things which happen at a certain date.
+Use them for information that is relevant for a specific event, like a talk or a meeting.
+
 This is not limited to events organized by the CCCHH, but can also be a hint to other events which we think are related to our activities.
 
 To create a new event blog post, run a command like this:
@@ -55,29 +87,30 @@ To create a new event blog post, run a command like this:
 hugo new content --kind event blog/yyyy/yyyy-mm-dd-your-event-title/index.md
 ```
 
-#### Add a Blog Entry
+If you want to create an event from scratch, or convert a blog post into an event, see the frontmatter data in [themes/ccchh/archetypes/event.md](themes/ccchh/archetypes/event.md).
-
+In particular, you need to set `categories: event`, `date:` for the date of the event, `publishDate:` for the date the content should be published, and `location:` to whereever your event takes place.
-As mentioned before, you can also create blog posts for things which aren't events.
-They will only be shown in the "blog" section and posted to the RSS feeds and shall be used for things which are relevant for a longer time.
-
-As we have much more event announcements than articles, finding articles in all blog posts can be quite a challenge.
-But using these two categories enables filtering, so that the history of articles is in one list.
-
-To create a new general blog post, run a command like this:
-```shell
-hugo new content --kind article blog/yyyy/yyyy-mm-dd-your-article-title/index.md
-```
 
 #### Additional Notes on Events and Articles
 
 By default the first 70 words are shown as a summary on list pages.
-Please use `<!--more-->` to manually separate the summary from other post content.
+Please use `<!--more-->` (white space matters) to manually separate the summary from other post content.
 
 Please prefix your folder name with a date to make browsing the content in the source code easier.
 The date in the URL will be taken from the `date` field in the front matter.
 
 Blog posts from before 2024-01-22 were imported from the previous website and have additional front matter data which is not usually needed (e.g. the lastmod value).
-When using the commands above, the template shall have evenything you need.
+
+#### Submitting Your Content
+
+After creating the new content, or making changes to existing content, please commit your changes with a meaningful commit message to a fresh branch. Name the branch in a way that makes it easy to understand what the changes are, for example, the title of your new blog post.
+
+Push the branch to git.hamburg.ccc.de, and create a new pull request. Invite reviewers, or post the link to the PR to the [#infrastruktur:hamburg.ccc.de](https://matrix.to/#/#infrastruktur:hamburg.ccc.de) Matrix channel.
+
+The changes you have made will be deployed to the staging website automatically (this might take a minute or two). See the comments in the PR for the link to your preview. You and the reviewers can use the link to preview the changes.
+
+If you have set a `publishDate` to a date and time in the future, the preview will show the content as it would appear then.
+
+Once at least one reviewer approves the PR, it will be merged and pushed to production. This usually takes less than five minutes.
 
 #### Populate the Event Calendar