Skip to content
Merged

X #226

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Guidance for AI contributors

Before creating or revising documentation, read the
[documentation authoring guide](CONTRIBUTING.md#writing-and-updating-documentation).
It applies to tutorials, feature guides, troubleshooting, and blog articles.
Verify the real workflow, write complete steps for a beginner, and keep the
article, examples, screenshots, and recordings consistent. Correct an existing
guide when it already covers the task; create a new page for a distinct outcome.

Before adding or changing tutorial recordings, video players, video metadata,
or watch pages, read the
[video contributor notes](CONTRIBUTING.md#adding-or-updating-tutorial-videos).
Expand Down
259 changes: 257 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,14 @@
# Contributing to Open Research
:+1::tada: Thanks for taking the time to contribute! :tada::+1:
# Contributing to Phoenix Code documentation

Use this guide when writing, updating, or reviewing Phoenix Code documentation.
It applies to human contributors and AI agents.

## Table of Contents

1. [About the Project](#about-the-project)
1. [Project Status](#project-status)
1. [Getting Started](#getting-started)
1. [Writing and updating documentation](#writing-and-updating-documentation)
1. [Adding or updating tutorial videos](#adding-or-updating-tutorial-videos)

## Community engagement
Expand All @@ -24,6 +29,256 @@ Documentation for phoenix/brackets
# Getting Started
* see https://github.com/phcode-dev/docs/blob/main/README.md

# Writing and updating documentation

The goal is a page a new user can follow to a checked result. Use this workflow
for tutorials, feature guides, troubleshooting, and practical blog posts. Scale
it to the change: a wording correction does not need a new recording or practice
project. The [image tutorial](docs/10-Tutorials/01-add-images.md) and
[single-file replacement tutorial](docs/10-Tutorials/06-find-and-replace.md) show
the established structure and shared components.

## Choose the reader's task and the right page

- Start with a concrete outcome and the reader's starting point. Search queries,
support questions, and observed mistakes can reveal a gap; a model's answer
is not evidence that a product feature exists. Summarize private user examples
without publishing account details or conversation identifiers.
- Search existing guides before creating a page. Correct or extend the relevant
guide when the outcome is the same. Create a separate page when the scope or
workflow differs, then link related pages. Finding text across files and
replacing text in one file, for example, need different instructions.
- Keep established slugs and useful section anchors when revising a page. If a
heading changes, retain its old explicit ID where appropriate. Follow the
site's redirect conventions when a URL must change.
- Keep one main task per tutorial. Put prerequisites before the steps and
optional variants or troubleshooting after them. A short conceptual answer
does not need to become a tutorial.

## Verify the workflow before writing it

Perform the task in the real product with the intended project and file open.
Check the edition, platform, application version, and whether you are using the
desktop or web app. Record those details and the check date in the review notes.
Use a fresh practice copy when trying alternatives so earlier edits do not hide
missing steps or override later settings.

- Check the complete path: open the project and file, select the right object,
enter the required mode, open the panel, change the value, apply it, save, and
inspect the result. Include dialogs that can appear along the way.
- Copy control names and locations from the actual interface. A command constant
or preference key in source code does not establish a visible menu or switch.
Check source code or official product documentation for behavior the interface
cannot show; distinguish that evidence from a workflow you ran yourself.
- State availability accurately. A free feature demonstrated while signed in
to Pro is not proof that the recording used a Community-only account. Verify
edition support before labeling the steps.
- For configuration, verify the file location, exact key and value, save/restart
requirements, scope, and limitations. For dependencies, cover the supported
operating systems or link directly to the installation steps.
- Inspect the saved file or exported output, not only the preview. Editing an
existing element should preserve unrelated attributes, classes, styles, and
content. Replacing a picture normally changes its `src` and `alt` values;
pasting a new whole tag can remove the reader's layout settings.
- If verification is incomplete, record the specific gap in the handoff. Do not
invent a control or present an untested procedure as verified.

## Write complete steps in plain language

Open with what the reader will accomplish, which editions it works in, and what
they need. Use familiar words and active verbs. Explain a technical term when
the reader first needs it, such as a project being the folder containing their
files. Remove promotional filler and vague claims; keep the details needed to
finish the task. A language review should improve clarity and accuracy, not
replace product verification with an AI-tone score.

1. Tell the reader where to start. Name the project, active file, or selected
object where it matters. Offer a skip-ahead link when setup is already done.
2. Describe one action or a short sequence in each numbered step. Use the exact
control label and its location. Give a menu or visible-button route before
optional shortcuts, including platform differences where needed.
3. Say what changes after the action. A selected state, highlighted match, open
dialog, or changed preview helps the reader recognize the right screen.
4. For code, identify the file and insertion or edit location. Say whether to
insert new content or edit an existing value. Use a language-tagged code block
for code to copy, and explain each placeholder to replace.
5. Include applying and saving changes, the file affected, and a visible result
to check. For operations affecting several files or elements, explain the
scope before applying them and give only verified undo instructions.

Prefer “Click the magnifying glass at the top left to open Find in Files” over
“Use the powerful search functionality.” A screenshot supports a step; it does
not replace an omitted instruction for reaching that screen.

## Show editions, platforms, and practice files clearly

When Pro and Community use different methods, show **Phoenix Pro first and by
default**, followed by **Community (free)**. Use the existing Docusaurus tabs:

```jsx
<Tabs groupId="tutorial-edition" queryString="edition" defaultValue="pro">
```

Import `Tabs` and `TabItem` as in the image tutorial, and use `pro` and `community`
as the tab values. Put descriptive headings inside each tab. Link to the relevant
edition and section using `?edition=community#section-id`, with the query before
the hash. Preserve a reader's explicit edition choice. See the
[Docusaurus tab documentation](https://docusaurus.io/docs/markdown-features/tabs#query-string).

If both editions use the same steps, say so once and share the procedure. Label
platform differences where they affect the action instead of duplicating an
entire guide. Never describe a Pro-only control as available in Community.

For Pro visual-editing tasks, show Design Mode when its larger preview helps.
Explain how to enter it and enable Edit Mode when needed. Community code-editing
tasks should show the editor beside Live Preview and explain Highlight Mode
where it locates the code. These are different modes; use their actual names.

Add a practice project when it helps readers reproduce the task. Reuse a suitable
project in `static/tutorials/` before creating another. Explain extraction, Open
Folder, the file to open, and the starting result. Make a sample optional when
the task works equally well in the reader's own file. A new packaged project
also needs registration in [package-tutorials.cjs](scripts/package-tutorials.cjs)
and the relevant release verification. Keep its source, ZIP, written examples,
screenshots, and recordings in agreement.

## Use recognizable icons and useful screenshots

- Pair a control's shape with its written name and location. Reuse
[TutorialIcon](src/components/TutorialIcon/index.js), for example
`<TutorialIcon name="preview" label="lightning bolt" />`. Use the actual
product icon, not an emoji substitute. Add new shapes and their attribution
to the shared icon map; follow the
[icon maintenance notes](config/search/README.md#small-control-icons-in-answers).
- Capture the real interface in the correct project, file, mode, and edition.
Do not generate or redraw product screenshots to imply a feature exists.
Remove private account data, credentials, and unrelated windows from the
capture setup. Use sample assets with a known license and keep attribution.
- Show the relevant control and enough surrounding interface to locate it.
Keep menus, property rows, values, and results fully visible. Scroll or enlarge
a panel before capture instead of publishing a clipped screenshot.
- Put each screenshot beside the step it explains. Write alternative text that
describes the relevant state or action. Use a stable public asset path and a
link to the full-size image when small details matter, as in the image tutorial.
Keep published assets available while older pages or answers still link to them.
- Check images at the article's display size on desktop and mobile, in light and
dark themes. Supply correct dimensions when writing raw `<img>` markup. Use
one clear visual cue at a time; do not cover the control with an annotation.

## Keep recordings consistent with the article

Read the [video contributor notes](#adding-or-updating-tutorial-videos) before
changing any recording, player, metadata, or watch page. Use a recording when
motion helps explain the task. Aim for under 30 seconds for a new short task clip,
and honor any explicit duration limit; preserve understandable actions rather
than rushing to fit a target. For longer tasks, consider separate focused clips.

Plan the actions, remove idle time, highlight the relevant control, and finish on
the actual saved result. State setup already completed outside the recording.
When a procedure changes, review its screenshots, recording, captions, poster,
and shared metadata together. Do not leave a video teaching the superseded steps.
Use a poster with the video's aspect ratio to avoid a size change on playback.

Keep the complete written guide readable without playing a video. Reuse the
shared player and watch-page components, and follow the existing rules for
autoplay, reduced motion, captions, publication dates, and video discovery.

## Structure pages for readers, search, and Ask AI

Use descriptive titles and headings, an accurate description, stable URLs, and
useful links from related guides. In Docusaurus docs, front matter supplies the
page title; avoid adding a second H1. Set a relevant social image when one is
available. See the official
[front-matter reference](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter).
For blog posts, also follow the existing author, date, tag, and excerpt conventions,
including `<!-- truncate -->` after a useful introduction.

Use this outline when starting a tutorial. Replace all example values and
prompts with verified content; omit sections that do not serve the task.

```md
---
title: Complete a specific task
slug: /tutorials/task-name
description: Describe the outcome and method in one useful sentence.
toc_max_heading_level: 2
---

Explain the outcome and which editions support it.

**You'll need:** Name the required files, software, and starting state.

## 1. Open the project or file

Give the verified setup steps and expected starting screen.

## 2. Make the change

Give numbered actions, with edition tabs only when the methods differ.

## 3. Save and check

Name the save action and the result the reader should see.

## Need help?

Answer problems observed while following these steps.
```

- Make important steps, edition restrictions, and caveats available as text.
Group each instruction with its relevant heading and illustration so search
and Ask AI can retrieve a useful explanation. Keep full-size image links
crawlable; do not rely on a screenshot's text or a video alone.
- Add FAQs for real reader problems, with direct answers and concrete fixes.
Do not pad a page with repeated questions or keywords. Keep any structured
data consistent with visible content and reuse the site's existing mechanisms.
- Fix missing or incorrect information in the source guide. Do not add a recipe
for each question to the AI prompt. Readers may use a short request, a typo,
or a follow-up; sample varied wording when reviewing generated answers.
- Check the generated canonical URL, sitemap entry, and crawl/index permissions
for new public pages. Review generated `llms.txt` entries where applicable;
change the source or generator rather than hand-editing build output.
- Judge quality by accuracy, completeness, and whether a reader can succeed.
[Google's content guidance](https://developers.google.com/search/docs/fundamentals/creating-helpful-content)
emphasizes useful, reliable content for people. A style score, FAQ, video,
metadata field, or `llms.txt` file is not proof that Google has indexed a page.

## Review, release, and hand off

For published tutorial or blog changes, follow the
[tutorial release checks](README.md#tutorial-release-checks). Register new
tutorials, blog routes, and video registries in
[verify-tutorials.cjs](scripts/verify-tutorials.cjs) where applicable; it does not
automatically discover every new page. Use JavaScript for verification code.
Keep checks focused on meaningful behavior; prose edits do not need tests that
merely assert the new wording. For contributor-notes-only changes, review links
and the diff; a site build is unnecessary.

Before release, follow the [dependency maintenance rules](AGENTS.md#package-upgrades-and-docsearch-maintenance).
Use the [search checks](README.md#search-and-ask-ai-checks) for search or Ask AI
changes. Keep shared tooling changes limited to what the documentation needs.

Review the built page as a new reader. Follow the complete workflow from its
stated starting point, check every documented edition/platform variation, and
test links, downloads, code examples, screenshots, and saved results. Inspect
desktop and mobile layouts in light and dark themes. Check keyboard access and
the selected tab after opening an edition-specific link; follow the additional
visual checks for video pages. If a platform or behavior could not be checked,
state that limitation instead of marking the entire review complete.

After deployment, check the live page and its assets. When indexed content has
changed, recrawl Algolia and test fresh answers against the new source, including
citations, screenshots, icons, and code formatting where relevant. Content-only
updates do not require republishing crawler settings or agent prompts. Use the
[search maintenance guide](config/search/README.md) when those settings also
change. Check Google indexing separately in Search Console; an Algolia crawl
does not request or confirm Google indexing.

Leave a short handoff with the changed pages, product verification details,
checks actually run, remaining limitations, and commit or preview link. Distinguish
what is local, committed, deployed, recrawled, and confirmed indexed. Name the
next required action without claiming that an unperformed check passed.

# Adding or updating tutorial videos

Use these notes when adding recordings, changing a video player, or creating a
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@
This repository hosts the code for https://docs.phcode.dev/ . Please contribute
to this repo for helping the Phoenix/Brackets community.

For contributors and AI agents, start with the
[documentation authoring guide](CONTRIBUTING.md#writing-and-updating-documentation).
It covers planning, product verification, writing, media, and release review.

## License

CC BY License Copyright (c) 2022-present, core.ai
Expand Down
Loading
Loading