# UNDRR writing guides

Writing guides for each type of content on undrr.org and PreventionWeb, for editors, partners and AI tools. Each guide covers what that content type is for, how to structure it and what good looks like.

> **About this guidance:** these guides summarize guidance maintained elsewhere, for reference. If a guide conflicts with the UNDRR Publications SOP or UNDRR Communications team guidance, those win; if you can't consult them, apply the guide and flag the point. The full list is under [sources](#sources). Found a problem? See [feedback](#feedback).

## Guides

| Guide | What it covers |
|---|---|
| [News](news.md) | Updates, op-eds, press releases, research briefs and other news types |
| [Events](events.md) | Conferences, webinars, training and launch events, before and after the date |
| [Publications](publications.md) | Summarizing reports and other documents, built on the Communications team's abstract guidance |
| [Blogs](blogs.md) | What an edited blog post looks like, from the Communications team's guidance for blog editors |
| [Metadata](metadata.md) | Choosing themes, hazards and countries, and other fields that affect discovery |
| [Taxonomy reference](taxonomy.md) | Themes, hazards, countries and regions with their term IDs, generated from the production taxonomy |
| [Methodology and maintenance](methodology.md) | Where the baseline figures come from, their limits and how the guides are maintained |
| [Instructions for AI writing assistants](ai-agent-instructions.md) | Which guide answers which question, and what wins when they conflict |
| [Using the guides with an AI assistant](agent-recipes.md) | Which files to give an AI tool and ready-made setups for reviewing news, summarizing publications, editing blogs and writing event pages |

## How UNDRR guidance fits together

Each kind of guidance has one home. Guides link to each other instead of repeating each other.

1. **Mechanics:** spelling, capitalization, punctuation, numbers, dates, abbreviations, UNDRR terminology and inclusive language are in the [Mangrove editorial manual](https://mangrove.undrr.org/llms-editorial-manual.txt) (plain text; [rendered version](https://mangrove.undrr.org/?path=/docs/contributing-editorial-manual--docs)). These guides link to it and don't restate it. UNDRR style follows the UNDRR Publications SOP where it departs from general United Nations style, most notably "25%" rather than "25 per cent"; the manual lists these differences and why under "Where UNDRR style differs from United Nations style".

   For writing principles beyond mechanics (purpose, audience, clarity and conciseness, diplomatic language), see the United Nations [A Handbook for Writers of the United Nations](https://languages.un.org/sites/default/files/2024-01/writing_for_the_united_natons_a_handbook_of_guidelines_techniques_and_resources.pdf) (PDF, version 1, 10 June 2023).
2. **Content-type writing guides:** this directory.
3. **Page building:** landing pages, components and search widgets are in the Mangrove documentation: [page building guide](https://mangrove.undrr.org/llms-page-building.txt) (plain text; rendered versions: [Building landing pages](https://mangrove.undrr.org/?path=/docs/patterns-building-landing-pages--docs) and [Drupal Gutenberg integration](https://mangrove.undrr.org/?path=/docs/getting-started-integration-drupal-gutenberg--docs)) and the [search widget editor configuration](https://mangrove.undrr.org/llms-search-widget.txt) (plain text; [rendered version](https://mangrove.undrr.org/?path=/docs/components-syndicated-search-editor-configuration--docs)). For term IDs, use the [taxonomy reference](taxonomy.md).
4. **Internal UNDRR style:** the Publications SOP, sensitive or political wording and anything else not for public use, on SharePoint.
5. **Editorial workflow:** review and approval, working with authors, commissioning and embargoes, on SharePoint.

For UX writing in interfaces, see Mangrove's [writing guidelines](https://mangrove.undrr.org/?path=/docs/contributing-writing-guidelines--docs). Their "address the user as you" rule is for interface copy, not articles.

### Decisions that apply to every guide

- **Headings and titles use sentence case**, with lower case after a colon, except menu and navigation labels, which capitalize each major word, and publication titles, which capitalize the main words and the first word of any subtitle (see the [Mangrove editorial manual](https://mangrove.undrr.org/llms-editorial-manual.txt), section: Capitalization).
- **Publication summaries follow the Communications team's abstract structure.** Where earlier drafts or the December 2025 baseline differ, the Communications guidance wins.
- **First person:** UNDRR content doesn't use "we", "our" or "I". Guest-authored blogs and signed op-eds may use first person where it rests on the author's firsthand experience, with no undefined institutional "we" (see [blogs](blogs.md#first-person)).

## All content types

These apply whatever the content type:

- **United Nations documents:** link through the Official Document System using the document symbol, for example `https://undocs.org/A/RES/69/283` for the Sendai Framework resolution. Don't link to unofficial copies.
- **Link text:** say where the link goes ("Read the Sendai Framework for Disaster Risk Reduction 2015–2030"), never "click here" or "read more". Mention the format and size for file downloads, for example "(PDF, 2.3 MB)".
- **Headings:** use them in order (H2, then H3) without skipping levels, and never just to make text bold or large.
- **Images:** give every meaningful image alt text that describes its content or purpose, without "image of".
- **Attachments:** use descriptive file names (not "document1.pdf") and accessible, tagged PDFs where possible.
- **Tables:** use header cells and keep tables simple; a list is often clearer.
- **Plain language:** short sentences, jargon explained, written for an international audience that may be reading in a second language.

## For UNDRR staff

Internal guidance lives on SharePoint. These links only work for UNDRR staff; the public guides don't reproduce their content. For a style question, check the Publications SOP first, then the Web Style Guide for points specific to web pages.

- [UNDRR Publications SOP](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Publications.aspx) (UNDRR staff only): the UNDRR house style for publications, and the source of the UNDRR-specific rules in the editorial manual
- [Web Style Guide](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Web-Style-Guide.aspx) (UNDRR staff only): style for web content on UNDRR sites
- [Internal UNDRR style guidance: editorial style and spelling](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Policies-and-SOPs.aspx#editorial-style-and-spelling) (UNDRR staff only): internal style points that are not for public use
- [Editorial workflow: Communications policies and SOPs](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Policies-and-SOPs.aspx) (UNDRR staff only): review, approval and working with authors
- [Longevity and interestingness guidance](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Longevity-Interestingness.aspx) (UNDRR staff only): choosing values for the Longevity and Interestingness fields

## Sources

The guides bring together guidance maintained elsewhere. Where a guide differs from one of these sources, or doesn't cover a point, the source wins:

- The [UNDRR Publications SOP](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Publications.aspx) (UNDRR staff only)
- The [UNDRR Web Style Guide](https://unitednations.sharepoint.com/sites/UNDRR-DRR-COMMS/SitePages/Web-Style-Guide.aspx) (UNDRR staff only)
- Guidance from the UNDRR Communications team, including its abstract writing guidance (the basis of the [publications](publications.md) guide) and its blog editing checklist (the basis of the [blogs](blogs.md) guide)
- The [United Nations Editorial Manual](https://www.un.org/dgacm/en/content/editorial-manual), whose mechanics the [Mangrove editorial manual](https://mangrove.undrr.org/llms-editorial-manual.txt) summarizes ([rendered version](https://mangrove.undrr.org/?path=/docs/contributing-editorial-manual--docs))
- For term names and IDs, the taxonomy and field configuration on the UNDRR Drupal platform as deployed; the [taxonomy reference](taxonomy.md) is a generated copy

If you can't consult a source, apply the guide and flag the point for someone who can check it.

## Feedback

Found a problem, or a guide that doesn't match current practice? Report it in the [Mangrove issue queue](https://github.com/PreventionWeb/undrr-mangrove/issues). A GitHub account is needed to open an issue.

## Using these guides with an AI tool

Use a prompt like this in any AI tool that can fetch URLs:

> Using the UNDRR publications writing guide at https://assets.undrr.org/docs/editorial-guides/publications.md and the Mangrove editorial manual at https://mangrove.undrr.org/llms-editorial-manual.txt, summarize the attached report for PreventionWeb.

Swap in the guide for your content type (`news.md`, `events.md`, `blogs.md`) and replace everything after the URLs with your brief. For tagging, add the [metadata guide](https://assets.undrr.org/docs/editorial-guides/metadata.md) and, for term IDs, the [taxonomy reference](https://assets.undrr.org/docs/editorial-guides/taxonomy.md). To set up a reusable agent, start from the [instructions for AI writing assistants](ai-agent-instructions.md).

If your tool can't fetch URLs or connect to SharePoint, give it the files yourself. [Using the guides with an AI assistant](agent-recipes.md) says where to get the Word copies, which files to upload for each job and what instructions to paste.

Check the output: AI tools can invent quotes, figures and sources, and a draft is only as accurate as the document or notes it is based on.

Maintaining the Microsoft 365 Copilot editorial agent? It can't fetch URLs, so it uses Word copies of these guides. See [`scripts/export-editorial-guides.md`](https://gitlab.com/undrr/common/shared-web-assets/-/blob/main/scripts/export-editorial-guides.md) in the repository for how to export and upload them.

## Changelog

| Date | What changed |
|---|---|
| 2026-09-30 | Added [using the guides with an AI assistant](agent-recipes.md): which files to give an AI tool and ready-made setups for common editorial jobs (undrr/web-backlog#3109) |
| 2026-09-29 | Initial publish: news, events, publications, blogs, metadata and methodology guides with curated examples, a taxonomy reference generated from the production taxonomy and AI agent instructions, consolidated from undrr/drupal-base!88 and Communications team guidance (undrr/web-backlog#3109) |

Last updated: 2026-09-30