contibutors guides update first pass

Author: rosieyohannan

CONTENT_AUTHORING.md

@@ -1,4 +1,4 @@
-# CircleCI Docs Static Site: Content Authoring Guide
+# CircleCI docs content authoring guide
 
 This guide provides comprehensive information for authors contributing content to the CircleCI Docs Static Site.
 
@@ -47,14 +47,13 @@ component/
 
 ## AsciiDoc Essentials
 
-The CircleCI Docs Static Site uses [AsciiDoc](https://asciidoc.org/) for content authoring. Here's how to use it effectively:
+The CircleCI docs site uses [AsciiDoc](https://asciidoc.org/) for content authoring. Here's how to use it effectively:
 
 ### Basic Syntax
 
 ```asciidoc
 = Page Title
-:description: A brief description of the page content
-:page-toclevels: 3
+:page-description: A brief description of the page content
 
 == Section Heading
 This is a paragraph of text.
@@ -71,22 +70,27 @@ Another paragraph with *bold text* and _italic text_.
 .. Nested numbered item
 ```
 
+For a more complete example, see the [template pages](https://github.com/circleci/circleci-docs/tree/main/docs/contributors/modules/templates/pages).
+
 ### Document Attributes
 
 Document attributes control various aspects of rendering:
 
 ```asciidoc
 = Page Title
-:description: Used for SEO and meta description
-:page-toclevels: 3     # Controls table of contents depth
-:page-layout: default  # Page layout template
-:experimental:         # Enables experimental features
-:icons: font           # Uses font icons
+:page-platform: Cloud, Server     # Displays platform badges in the page info bar
+:page-description: Used for SEO and meta description
+:experimental:                    # Enables macro features for menu and button macros
+:page-aliases: some-old-page.adoc # redirects archived pages
+
 ```
 
 ### Page Title Badges
 
-Add visual badges next to page titles to indicate content status (e.g., Preview, Beta, Deprecated):
+Add visual badges next to page titles to indicate content status. Currently we are using a `Preview` badge to indicate when a page is for a feature in open or closed preview.
+
+A page is closed preview will display the `Preview` badge and **will not be** listed in the navigation.
+A page in open preview will display the `Preview` badge and **will be** listed in the navigation.
 
 #### Basic Usage
 
@@ -117,23 +121,12 @@ This displays a simple badge with default styling (black text, border, no backgr
 
 #### Common Badge Styles
 
-**Preview (Orange):**
+**Preview:**
 ```asciidoc
 :page-badge: Preview
-:page-badge-classes: text-white bg-orange-500 border border-orange-600
 ```
 
-**New (Green):**
-```asciidoc
-:page-badge: New
-:page-badge-classes: text-white bg-green-500 border border-green-600
-```
-
-**Deprecated (Red):**
-```asciidoc
-:page-badge: Deprecated
-:page-badge-classes: text-white bg-red-500 border border-red-600
-```
+Currently we are not adding styling to these badges but this may change in future.
 
 #### Badge Attributes Reference
 
@@ -162,31 +155,8 @@ CAUTION: This requires special attention.
 
 ### Page Structure Template
 
-Use this template as a starting point for new pages:
-
-```asciidoc
-= Page Title
-:description: Concise description of the page content
-:page-toclevels: 3
-
-[abstract]
---
-A brief introduction to what this page covers and why it's important.
---
+Use the [template pages](https://github.com/circleci/circleci-docs/tree/main/docs/contributors/modules/templates/pages) as a starting point for new content.
 
-== First Major Section
-Introduction to this section.
-
-=== Subsection
-Content for the subsection.
-
-== Second Major Section
-Content for the second major section.
-
-== Related Information
-* xref:related-page.adoc[Related Page]
-* xref:another-related-page.adoc[Another Related Page]
-```
 
 ### Headings
 
@@ -197,7 +167,6 @@ Use hierarchical headings to structure your content:
 == Level 1
 === Level 2
 ==== Level 3
-===== Level 4
 ```
 
 Avoid skipping levels, and don't go deeper than level 4 unless absolutely necessary.
@@ -209,6 +178,7 @@ Avoid skipping levels, and don't go deeper than level 4 unless absolutely necess
 For code blocks with syntax highlighting:
 
 ```asciidoc
+.Title for code block, explain what it is and what it does
 [source,yaml]
 ----
 version: 2.1
@@ -225,9 +195,11 @@ jobs:
 
 ### Tables
 
-Create formatted tables:
+Create formatted tables that can scroll horizontally as needed:
 
 ```asciidoc
+[.table-scroll]
+--
 .Table Title
 [cols="1,1,2", options="header"]
 |===
@@ -241,6 +213,7 @@ Create formatted tables:
 |Row 2, Cell 2
 |Row 2, Cell 3
 |===
+--
 ```
 
 ### Tabs
@@ -265,6 +238,8 @@ Content for Tab B
 
 ### Collapsible Sections
 
+**We do not currently use collapsible sections.**
+
 For long content that might be hidden initially:
 
 ```asciidoc
@@ -285,10 +260,16 @@ Link to other pages within the documentation:
 xref:page-name.adoc[Link Text]
 ```
 
+To link to a page in another module in the same component:
+
+```asciidoc
+xref:module-name:page-name.adoc[Link Text]
+```
+
 To link to another component:
 
 ```asciidoc
-xref:component-name:page-name.adoc[Link Text]
+xref:component-name:module-name:page-name.adoc[Link Text]
 ```
 
 To link to a specific section:
@@ -305,6 +286,8 @@ Link to external resources:
 link:https://circleci.com[CircleCI Website]
 ```
 
+The `link:` is not strictly necessary but makes it easier to find when editing or making bulk changes.
+
 ### Navigation Files
 
 The `nav.adoc` file defines the sidebar navigation structure:
@@ -324,6 +307,7 @@ The `nav.adoc` file defines the sidebar navigation structure:
 Include images with optional attributes:
 
 ```asciidoc
+.Image title
 image::filename.png[Alt Text,width=500,role=center]
 ```
 
@@ -340,9 +324,19 @@ video::video-id[youtube,width=640,height=360]
 
 ### Diagrams
 
-For complex diagrams, use image files created with diagramming software.
+You can add mermaid diagrams to a page, as follows:
 
-For simple diagrams, you can use AsciiDoc's built-in diagramming through extensions like Asciidoctor Diagram.
+```asciidoc
+.Example of a mermaid diagram
+[mermaid]
+....
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>Bob: Hello Bob, how are you?
+    Bob-->>Alice: Great!
+....
+```
 
 ## Semantic Guidelines
 
@@ -365,11 +359,11 @@ Structure your content based on its purpose:
 
 ### Versioning Content
 
-For version-specific content, use conditional statements:
+For version-specific content, use negative conditional statements ([ifndef directive](https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/)) :
 
 ```asciidoc
-ifeval::["{serverversion}" == "4.0"]
-This content is only visible for server version 4.0.
+ifndef::aws
+This content is only visible for non-AWS pages and sections
 endif::[]
 ```
 
@@ -391,18 +385,8 @@ Before submitting content for review, check that:
 
 All content should go through peer review:
 
-1. Create a pull request with your changes
-2. Request review from subject matter experts
-3. Address any feedback or suggestions
-4. Update based on technical accuracy review
-5. Final editorial review for consistency and style
-
-### Common Feedback Points
-
-- Technical accuracy and completeness
-- Structure and organization
-- Language clarity
-- Cross-referencing correctness
-- Code sample functionality
-- Image quality and relevance
-- Navigation placement
+1. Create a pull request with your changes. Code ownders will be pinged for review automatically (docs team and PM team).
+2. Request review from subject matter experts, for most changes we will want a review from an engineer in the relevant team or the PM for the feature. The docs team can manage this process for you.
+3. Address any feedback or suggestions.
+4. Update based on technical accuracy review.
+5. Final editorial review for consistency and style.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # CircleCI Docs Static Site: Contributing Guide
 
-This guide provides comprehensive information for contributors to the CircleCI Docs Static Site project.
+This guide provides comprehensive information for contributors to the CircleCI docs project.
 
 ## Table of Contents
 - [Ways to Contribute](#ways-to-contribute)
@@ -14,19 +14,18 @@ This guide provides comprehensive information for contributors to the CircleCI D
 
 ## Ways to Contribute
 
-There are several ways to contribute to the CircleCI Docs Static Site:
+There are several ways to contribute to the CircleCI docs project:
 
 1. **Documentation content**: Add or improve documentation pages
 2. **Technical improvements**: Enhance the site's functionality
 3. **UI improvements**: Improve the user interface and experience
 4. **Bug fixes**: Fix issues with the site or content
-5. **Feature requests**: Suggest new features or improvements
+5. **Feature requests**: Suggest new features or improvements. You can do this by submitting a [GitHub issue](https://github.com/circleci/circleci-docs/issues) or using the feedback form on the docs site itself.
 
 ### Types of Contributions Needed
 
 - Writing tutorials and how-to guides
 - Improving API and reference documentation
-- Translating content
 - Fixing typos and clarifying explanations
 - Developing new UI components
 - Improving build performance
@@ -45,7 +44,7 @@ There are several ways to contribute to the CircleCI Docs Static Site:
 
 1. **Fork the repository**:
    - Visit [https://github.com/circleci/circleci-docs](https://github.com/circleci/circleci-docs)
-   - Click the "Fork" button to create your own copy
+   - Click the "Fork" button to create your own copy. If you are a CircleCI employee you can simply clone the repo rather than creating a fork.
 
 2. **Clone your fork**:
    ```bash
@@ -109,12 +108,12 @@ Example: `docs/add-kubernetes-guide` or `fix/broken-navigation`
    git commit -m "Your commit message"
    ```
 
-   Commit message format: 
+   Commit message format:
    ```
    type(scope): Brief description
-   
+
    Longer description if needed
-   
+
    Fixes #123
    ```
 
@@ -194,9 +193,10 @@ function performTask(input) {
 
 ### Types of Tests
 
-- **Content validation**: Ensuring documentation is accurate
-- **Link checking**: Verifying all links work correctly
-- **UI testing**: Checking for visual and interactive issues
+- **Content validation**: This is a manual text. As far as reasonably possible all docs changes and additions should be manually tested. A member of the CircleCI docs team (or other team) should run through the documented task following any steps outlined in the doc closely to check they are both correct and complete, no missing steps where users could get stuck. Changes to technical content should be reviewed by a member of the engineering team that owns the feature.
+- **Content style checking**: We use [Vale](https://vale.sh/) for content linting. We have vale rules set up to enforce style. You can take a look at these rules in the `/styles` folder. Vale runs in our CI/CD pipeline so you can check for error and warnings when pushing your changes to GitHub. You can also install vale locally on your machine and run vale on the file you are editing or even using an [extension in your IDE](https://marketplace.visualstudio.com/items?itemName=chrischinchilla.vale-vscode).
+- **Link checking**: Verifying all links work correctly. Links are checked as part of our CI build
+- **UI testing**: Checking for visual and interactive issues (we do not currently have any UI testing set up)
 - **Build testing**: Ensuring the site builds correctly
 
 ### Running Tests
@@ -208,7 +208,7 @@ function performTask(input) {
   Review the site locally for content issues.
 
 - **Link checking**:
-  The CI pipeline includes automatic link checking.
+  The CI pipeline includes automatic link checking. Check the outcome of the `Validate` job for issues.
 
 ## Documentation Guidelines
 
@@ -251,13 +251,13 @@ All contributions go through a review process:
 - Are there adequate tests?
 - Does it follow project conventions?
 
-### After Approval
+During the review process further discussion might be needed. This will happen in comments in the PR. The docs team review might push changes to your branch to fix style and formatting issues but larger issues will be discussed first.
+
+The speed at which we can process changes will depend on the scope of the change and the existing workload that the docs team has at that time. We would try to respond to contributions within two days of submission.
 
-Once your PR is approved:
+### After Approval
 
-1. It will be merged by a maintainer
-2. Your contribution will be included in the next release
-3. You'll be credited as a contributor
+Once your PR is approved it will be merged by a maintainer. Your contribution will be published immediately (well, around 4 minutes for the pipeline to build!)
 
 ## Release Process
 
@@ -266,16 +266,14 @@ Once your PR is approved:
 The CircleCI Docs Static Site follows a continuous delivery model:
 
 - Documentation changes: Released as soon as they're approved
-- Technical changes: Released on a scheduled basis
+- Technical changes: Released as and when ready
 - Emergency fixes: Released as needed
 
 ### Release Process
 
 1. Changes are merged to `main`
 2. CI pipeline builds and tests the site
-3. Automatic deployment to staging environment
-4. Review and testing in staging
-5. Deployment to production
+3. Deployment to production
 
 ### Versioning
 
@@ -295,12 +293,4 @@ If you need help with your contribution:
 - **Discussions**: Use GitHub Discussions for questions
 - **Documentation**: Refer to the technical docs
 
-## Recognition
-
-Contributors are recognized in several ways:
-
-- Attribution in commit history
-- Inclusion in the contributors list
-- Recognition in release notes for significant contributions
-
 Thank you for contributing to the CircleCI Docs Static Site!