Skip to main content
Version: Next Gen

Add new content

Make sure to consult with the Sr. Technical Writer when adding topics or want to propose changes to the content structure.

The Sr. Technical Writer maintains the content's quality, reduces duplication, and provides a consistent user experience. They can also strategize how to deliver complex information—for example, adding an explainer video (<90 secs) can help with complex scenarios or issues.

  1. Make sure you're back on the main (default) branch so you can sync your local working branch.

    git checkout main
    git pull origin main
  2. Create a working branch for your proposed changes. For example, content-dev-faqs or update-visual-guidelines.

    git checkout -b {your-branch-name}
  3. Navigate to /docs and locate the subdirectory for your new topic.

  4. Add the metadata (frontmatter).

    Keywords are optional but helpful. All other metadata is required.

    important

    The author metadata value is the Subject Matter Expert (Engineer, Developer, or Product Manager) rather than the Technical Writer.

    ---
    title: Threat Dashboard
    id: threat-dashboard
    description: 'The threat dashboard provides easy-to-use and intuitive threat intelligence analytics. This new dashboard will help you identify users, passkeys, and authentications that have displayed some risk over the last 0-90 days. Risky entities are added to low, medium, and high groups based on their score from 0-100. You can filter the view of this dashboard and the accompanying table based on these groups.'
    slug: /threat-dashboard
    keywords:
    - threat dashboard
    pagination_next: null
    pagination_prev: null
    last_update:
    date: 07/26/2023
    author: John Canneto
    draft: false
    doc_type: overview
    displayed_sidebar: secureWorkforceSidebar
    ---
  5. Add the new markdown file in the sidebar.js file.

    {
    type: 'category',
    label: 'Architecture',
    collapsed: false,
    collapsible: false,
    link: {
    type: 'doc',
    id: 'architecture/architecture',
    },
    items: [
    'architecture/overview',
    'architecture/architecture',
    ],
    },

    It's a best practice to add the markdown file early in the content development phase. Otherwise, you'll get an error when you run the command to build and review your content.

  6. Create your content and run the following command to build and review your changes.

    yarn start

    This command starts a local development server and opens a browser window. Most changes are reflected live without having to restart the server. If a browser window doesn't open, go to http://localhost:3000/ to view your local changes.

  7. Perform a self-review of your markdown and make sure your changes or additions follow the style guidelines.

  8. Verify that the PR does not generate warnings or errors, such as broken links. If so, address them and ensure it builds without issues.

    npm run clear
    yarn build
  9. When you're ready to submit a pull request, add your changes.

    git add --all
  10. Commit your changes with a descriptive summary, for example, Add clarity to the data table component usage examples.

    git commit -m "short description of the change"

    Ensure that your commit message is a proper sentence. Refer to this guide on writing good commit messages.

    A properly formed git commit subject line should always be able to complete the following sentence:

    If applied, this commit will ....

  11. Publish, or push, your changes to the main repo for merging.

    git push origin {your-branch-name}
  12. Create a pull request.