naif/publishing-guidelines.qmd at main · eth-library/naif · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
---
title: "Publishing guidelines"
toc: true
---

This guide explains how to prepare NAIF news posts and event pages. It is written for project partners and anyone contributing content.

## Who we are writing for

### Primary audiences

- NAIF project partners: shared alignment, progress transparency, coordination signals (public-facing).
- swissuniversities: public reporting, relevance for the sector, evidence of progress.
- ETH Board and other governance stakeholders: strategic value, interoperability outcomes, sustainability pathway.

### Secondary audiences

- Researchers, libraries, repository teams, the open science community, and the interested public.

### A simple structure that works well

- **Why it matters**: interoperability, metadata quality, responsible indicators, findability of Swiss research.
- **What we did**: activities, methods, consultations, analyses.
- **What we found**: interim insights, constraints, recommendations.
- **What's next**: planned actions, opportunities to engage, upcoming events.
- **What to reuse**: outputs with persistent identifiers (DOIs, ROR, ORCID references as relevant).

## Where content goes

- News posts: `posts/<yyyy-mm-dd>-<slug>/index.qmd`
- Events: `events/<yyyy-mm-dd>-<slug>/index.qmd`
- Images for a post go in that post's `images/` folder.
- Images for an event go in that event's `images/` folder.
- Do not edit files in `_site/`.

## Language and spelling

- Use British English for news posts and for event pages that are not reposts.
- Use sentence case for page titles and section headings by default.
- Preserve official branded styling for proper nouns, acronyms, and formal event names.
- Reposts may keep the original wording and spelling when needed.

## News post guidance

Use a news post for updates, findings, progress reports, or opinion pieces.

**Required information at the top of the page**

- `title` (<= 70 chars; use sentence case unless it reproduces an official branded name)
- `subtitle` (optional; concise one-line context)
- `date` (YYYY-MM-DD)
- `author`
- `description` (<= 280 chars)
- `other-links` (when there is a related event page)
- `categories`: choose one of `Track 1`, `Track 2`, `Track 3`, `Track 4`, `General`
- `tags`: exactly 3 tags
- `proofread`: `true` or `false`
- `image`: path to a local image

**Writing tips**

- Put the teaser in `description`.
- Do not add a separate lead section at the start of the page.
- Follow the simple structure above.
- Keep the post concise.
- If you are not using automatic references, add links in the text or use a `## Sources` or `## Further reading` section.
- Use academic titles (`Dr`, `Prof`, etc.) consistently where known.

## Event guidance

Use an event page for announcements and for documenting past events.

**Required information at the top of the page**

- `title` (<= 70 chars; use sentence case unless it reproduces an official branded name)
- `date` (YYYY-MM-DD)
- `author` (organiser name)
- `author-title`: `Organizer`
- `description` (<= 280 chars)
- `other-links` (when there is a related post page)
- `categories`: choose one of `Organised by NAIF`, `Participation by NAIF`, or `Related Topic`
- `tags`: exactly 3 tags
- `proofread`: `true` or `false`
- `image`: path to a local image

**Event details to include**

- Include the date and, where available, the time, location, registration link, and event page.
- For future events, keep the registration and event page links clickable.
- For past events, show old registration links as plain crossed-out text and add a short note that the event has already taken place.
- If a detail is not available, say so plainly.

## Images and rights

- Use 1-3 good-quality images where possible.
- Every image needs alt text, a caption, and a note on rights or source.

## Reposts of external content

- Republishing material that has already appeared elsewhere requires permission from the original publisher.
- Add a visible note near the top linking back to the original URL.

## External mentions

- Brief mentions of NAIF in newsletters, partner blogs, or internal channels should be added to `mentions/items.yml`.
- Use that page for short notices and link collections. Use a full news post only when we republish the original text with permission.

## Drafts

- Use `draft: true` for work in progress.
- Drafts appear in preview, but not in the published site.

## Reuse and identifiers

- Add stable identifiers such as DOIs, ROR IDs, or ORCID iDs when they are useful.
- NAIF deliverables are archived on Zenodo: [Zenodo community](https://zenodo.org/communities/naif)

## Templates

### News post template

```markdown
{{< include posts/_template-post/index.qmd >}}
```

### Event template

```markdown
{{< include events/_template-event/index.qmd >}}
```

## Code of conduct

All contributors are expected to follow this repository's code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).