This document provides a comprehensive guide for writing an article for Permit.io. It is structured to ensure that every article maintains clarity, consistency, and educational value while adhering to best practices for SEO and technical accuracy. The guidelines are organized as follows:

1. General Guidelines: These cover the basic expectations for article structure, including title formatting, meta descriptions, and how to introduce the topic in a concise and engaging way.
2. Additional Notes: Here, we dive into specifics such as mentioning Permit.io, the importance of the Local PDP, and best practices for code snippets.
3. Topics to Cover by Article Type: This section breaks down the exact content that should be covered in articles depending on their type, such as RBAC implementation, adding authorization to an authentication provider, or integrating Permit.io with a database. Each type comes with its own set of technical steps, code examples, and considerations.

With these guidelines, your articles will be structured in a way that enhances the reader’s experience while providing them with practical, actionable information.

General Outline Guidelines

• The Title
  • A simple, short title that focuses on SEO keywords.
  • Titles should never mention HOW but rather focus on the WHAT.
  • Good Title: How to Implement RBAC in an Express.js Application
  • Good Title: Building an AI Banking Application in Express.js with RAG, and FGA
  • Bad Title: How to Build a Secure Express.js Flight Scheduling Application with Granular Access Controls Using Permit.io
  • Don’t mention Permit.io in the title. Don’t explain what the application does. Don’t use buzzwords (Secure/Robust/Powerful).
• Meta Description
  • Explain what a person can expect from this article.
  • Mention the required SEO keywords.
  • You can mention Permit.io here, but never make it about “Compliments”
  • Bad: Implement a powerful secure robust authorization with Permit.io - an awesome free special unique no-code AI SaaS solution
  • Good: Learn how to implement Role Based Access Control (RBAC) in Django with this step-by-step guide.
• Introduction
  • Always include an introduction
  • Never title it as “Introduction”. Having no title is the best title.
  • The introduction is basically a “Mini” version of the entire article without the code examples - it shares much of the same structure as the rest of the article but in very short points.
  • The introduction needs to explain the following things:
    • What framework(s) are we talking about, what it/they are used for
    • Why does it need authorization
    • If it provides some built-in solution (Like Django authorization), why isn’t that enough?
    • Introduce what we will be building
    • Mention the tools we are going to be using in the process.
    • When you mention Permit.io, you can mention what it does and how we will be using it in a few words. Note the language you use: This is a tutorial, NOT AN ADVERTISEMENT. Treat it as such.
  • The introduction should not be longer than 200 words.
• What Will We Build? / Feature Requirements / Use Case Introduction
  • Explain in short what your demo application does.
  • Explain in plain English what access control policies you are planning to implement.
  • Explain your desired application flow
• Optional: Theoretical Overview
  • If the application guides you through the implementation of a complex concept people might be unfamiliar with, such as Relationship-Based Access Control or Retrieval-Augmented Generation, this is the place to explain it.
  • Make the explanation short and to the point (Around 200 words). Include links to other blogs for further reading.
  • Provide examples relevant to this specific implementation.
  • Example: If you are doing a guide on how to implement ABAC into X, and you wish to explain what ABAC is, provide a few lines of explanation of ABAC as a general concept, followed by a simple example of an ABAC policy in plain English that you will be implementing later on in the tutorial.
  • Remember that these articles are not thought leadership. The goal is not to educate about complex concepts, but rather do a step-by-step walkthrough of an implementation.
• Prerequisites and Tech Stack
  • Describe, in short points, what tools the user can expect to use during the implementation process.
• The Implementation Guide

  • Before diving into the steps, explain what the steps are going to be.

  • When implementing authorization, the first step is ALWAYS the PLANNING STEP.

  • The planning step explains what resources, roles, attributes, and or relationships you are going to be implementing. Provide an organized list of these.

  • Explain the policies you will be implementing in the UI/API in simple English

  • Example:

    • Only doctors with valid relationships to a medical center can see its visits
    • Patients can view and edit their own visits.
    • Changes in relationships (e.g., doctor reassignment) immediately affect access rights

  • After the planning step is explained, you may continue with the rest of the setup.

  • The technical flow should be in the following order: Schema, Data, and Enforcement. Each topic needs to be separate.

    • Schema: everything in the Permit policy screen
      • Roles, resources, role derivations, resource relation, user/resource attributes (schema, not attribute values), users/resource sets, policy rules (checkboxes in policy screen)
    • Data: everything in the Permit Directory screen
      • Users, user attributes, user role (role assignment)
      • Resource instances, resource instance attributes
    • Enforcement: The permit.check() function (single and bulk), data filtering, partial evaluation.

  • Make sure your steps are broken down into points and explained clearly. Do not explain how to perform several actions in a single paragraph.

  • How NOT to describe steps:

    Go to X and create an account if you don't have one. Set up your organization, click on "Create New Project" to create a new project and provide the project name, click on next to pick the deployment region, we'll use the default region, and click on "Create" to create the project.

  • How to describe steps:

    Setting up X:

    • Go to the X website and create an account
    • Next, to set up a new project, click on "Create New Project” in the top right corner.
    • Pick the deployment region (We'll use the default region).
    • Finish the setup by clicking on "Create".

  • Please avoid numbering steps. This breaks very easily during editing/upload.

• Test / Showcase The Implementation Result
• Provide a conclusion for the article. A Conclusion should include:
  • What does this guide set out to achieve?
  • How was this achieved?
  • What did we gain from this?
  • CTAs: Read the docs / check out the Git Repo for the demo app / join the community.
  • Suggestions for further reading (See list below).

Additional Notes

• Demo Data:
  • If the article is not intended to be published under your name, please avoid using any personal details in the examples (Email, name, etc.) Use mockup names and data instead.
• Mentioning Permit.io:
  • Keep mentions short and to the point. Avoid using overly commercial language.

    • How NOT to mention Permit.io:

      This is where Permit.io comes in. Permit.io provides an easy-to-integrate, policy-based authorization solution that handles role management, permission enforcement, and API protection. You focus on building your application without worrying about access control logic. Permit also gives you a UI console, APIs, and SDKs to streamline permission checks in your app.

    • How to mention Permit.io:

      This blog will guide you through implementing RBAC in X using Permit.io - an authorization-as-a-service solution. You'll learn how to define roles, configure permissions, and enforce access control.

• Local PDP
  • Even if you’re using the cloud PDP, please mention the Local PDP and its advantages:
    • Zero-latency policy decisions
    • Local testing without the need for a cloud service