Define document front matter

[jorge-campo]

Background information

Front matter is a section at the very top of a file (often in YAML format) that contains metadata about the document. A front matter helps to categorize and uniquely identify a document in the repository.

In specific setups, the front matter is used to categorize, filter, sort, or process documents programmatically.

In the Status app documentation, we use a simple front matter where the document ID corresponds to the ID of the issue that led to the document. This approach, however, doesn't work when the document is updated in other issues with other numbers. In other words, the issue ID-document ID doesn't work well in the long term, but it ensures each document is unique, as a given repo can't have the same issue or PR ID (they're unique).

This is an example from the GitHub documentation:

---
title: Reviewing a pull request created by Copilot
shortTitle: Review Copilot PRs
intro: 'After {% data variables.product.prodname_copilot_short %} creates a pull request you should review it and comment on anything that needs changes.'
product: '{% data reusables.gated-features.copilot-coding-agent %}<br><a href="https://github.com/features/copilot/plans?ref_cta=Copilot+plans+signup&ref_loc=reviewing+a+pull+request+created+by+copilot&ref_page=docs" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Sign up for {% data variables.product.prodname_copilot_short %}</span> {% octicon "link-external" height:16 %}</a>'
versions:
  feature: copilot
topics:
  - Copilot
type: how_to
redirect_from:
  - /copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/reviewing-a-pull-request-created-by-copilot
  - /copilot/using-github-copilot/coding-agent/reviewing-a-pull-request-created-by-copilot
---

Questions

1. What mandatory fields should the front matter include?
2. Are there any dependencies we need to consider when using GitBook to generate the documentation site?
3. How can we uniquely identify each document? Do we need to identify them uniquely?

@cheny0

[cheny0]

1. Suggestion for frontmatter attributes:
   topic - waku, codex, ect.
   author - acknowledge the writer's work, encourage contribution and for readers to feel the article is trustworthy
   date - last update date, to show the information is up-to-date / could be outdated
   title or id- a unique identifier just in case we need it

2. I asked this question to GitBook's documentation AI assistant (see image). GitBook doesn't require frontmatter. It supports documents to include front matter for our internal use.
   

3.Based on our experience with the Status docs, I only use the document ID for linking images to the correct document. I'm not sure whether we need it for this purpose for IFT docs, it depends on how the images are managed. We can also use the document title for this purpose.

[jorge-campo]

3.Based on our experience with the Status docs, I only use the document ID for linking images to the correct document. I'm not sure whether we need it for this purpose for IFT docs, it depends on how the images are managed.

I think it's a good idea to be able to uniquely identify a document in the repo. This may not be very important in the Status docs, as there is only one project in the repository: Status. However, in a monorepo structure, all projects will work under the same repository, and having a way to identify documents might be useful.

We can also use the document title for this purpose.

How? For example, each project will have at least one "Quickstart" document.

[jorge-campo]

1. Suggestion for frontmatter attributes:
   topic - waku, codex, ect.
   author - acknowledge the writer's work, encourage contribution and for readers to feel the article is trustworthy
   date - last update date, to show the information is up-to-date / could be outdated
   title or id- a unique identifier just in case we need it

I like this list 👍 It's short, but I can't see any other things we need now. I would only change topic to project, though.

[cheny0]

How? For example, each project will have at least one "Quickstart" document.

The title for each quickstart could be "Quickstart for {feature/product name}". The title for an API reference could be "{feature/product name} API"

[jorge-campo]

Regarding the DocumentID, @cheny0

I checked what other projects like Docusaurus or GitHub Pages do for traceability, and had a long conversation with Kimi. Our goal is to uniquely identify a document so we can go back in time and see what happened with the document (this is a just-in-case scenario).

We already have git and GitHub's blame function to read any file history in GitHub. Unless a new version is written over a new file, we can always see the file history in detail (who made what, basically).

Nevertheless, it's nice to have a unique document identifier to refer to the document. This can be handy in many situations, such as the one we have with illustrations in Status Help, where Francesca uses the ID to organize the pictures. However, using the original ID number as the document ID is not ideal because, after several updates, this ID no longer corresponds to the document. It seems random.

I think the document title can be confusing, and it forces us to adapt the title, as you suggest ("Quickstart for {feature/product name}" instead of just "Quickstart"). Docusaurus and GitHub Pages use GitHub's document URL. The risk is that the URL can change if the document is renamed or moved, but I don't think this is very frequent.

Thoughts?

[jorge-campo]

So, we would have:

---
title: "Quickstart" <corresponds 1:1 with the Markdown file name>
topic: "Codex"
author: cheny0 <GitHub user name>
version: 1 <increased by one after every update>
url: docs/codex/quickstart.md
---

`date` is provided already by GitHub and GitBook. I see this as unnecessary.

[cheny0]

My concern is, if we use the document URL as the document ID, a major ID update will be needed when we move the existing docs to a new platform like GitBook.
Maybe we can combine the two methods. Except quickstart and API documents, it's unlikely for other documents to have the same title. We could change their IDs only instead of changing the titles. For example: codex/quickstart or quickstart-codex. 🤔

[jorge-campo]

My concern is, if we use the document URL as the document ID, a major ID update will be needed when we move the existing docs to a new platform like GitBook. Maybe we can combine the two methods. Except quickstart and API documents, it's unlikely for other documents to have the same title. We could change their IDs only instead of changing the titles. For example: codex/quickstart or quickstart-codex. 🤔

Let me elaborate on your idea, @cheny0 -- Why if we use {project-name}-{doc-name} as the document ID? You were close to this when suggesting quickstart-codex. With my proposal, we would have codex-quickstart as the ID. This way, we avoid any type of collision, because the shouldn't be duplicate name per project. Additionally, if the Codex project changes its name in the future, we can update front matters programmatically.