Topic Page Template

This page defines the layout of a reference topic under pages/topics: five parts in a fixed order, and the voice they are written in. JSON Serializers and JSON Parsers follow it and are the worked examples.

The five parts

A reference topic has up to five parts, in this order. Skip a part that does not apply; never reorder them.

#	Part	Heading	Content
1	What it is	none	One or two sentences, as the page's first paragraph. The page title already names the topic, so this part has no heading. generate-ai-artifacts.py uses this paragraph as the page summary.
2	When to use it	## When to use it	The situations the API is for, and the neighbouring API to use otherwise.
3	A complete example	## Example	A complete java fence where possible: a whole class or method, not the tail of a builder chain. Put it under the heading, not in a :::tip Example admonition.
4	Options and configuration	## Options	A table of up to about eight builder methods or annotation attributes readers reach for first, with their defaults, then a link to the builder or annotation Javadoc for the full list. For a serializer or parser, the pre-configured instances (DEFAULT, DEFAULT_READABLE, ...) count as options. Skip the part when there is nothing to configure.
5	See also	## See also	The guide that covers the topic, when one exists, first; then related topics.

A short topic may stay under 150 words when each part is short. The example is what matters.

Voice

• Present tense, second person: say what the API does and what you do with it.
• No tutorial narrative ("let's go back to our Person bean"); that belongs in a guide.
• No maintainer notes (commit hashes, snapshot pins, "TODO" remarks).

Examples

Fences follow the AI Knowledge Authoring Guide: every java fence is parsed by check-java-fences.py --strict, and fragment is allowed only for the cases that guide lists. The check parses the code but does not compile it or resolve names, so check every class and method name against the current Javadoc by hand.

Skeleton

The JSON Serializers page has this shape:

---
title: "JSON Serializers"
slug: JsonSerializers
---

The JsonSerializer class serializes POJOs into JSON text.

## When to use it

Use JsonSerializer when ... For a one-line conversion, use the Json marshaller instead.

## Example

```java
public class JsonSerializerExample {
    public static void main(String[] args) throws Exception {
        String json = JsonSerializer.DEFAULT.write(new Person());
    }
}
```

## Options

| Instance or builder method | Effect |
|---|---|
| `JsonSerializer.DEFAULT_READABLE` | JSON with whitespace and indentation. |
| `keepNullProperties()` | Write bean properties whose value is `null`. |

## See also

- [JSON Parsers](/docs/topics/JsonParsers)

Checking a page

scripts/check-topic-template.py reports pages under 150 words, pages with no code fence, and pages whose template headings are out of order. It is advisory and always exits 0.

python3 scripts/check-topic-template.py --chapter 03

It checks structure only; review the voice by hand.