Proposal: new architecture/structure for Apache APISIX Documentation

[avinal]

What needs Improvements?

Getting Started (needs improvements)

Missing Introduction page - must have a proper introduction (partial)

• What is an API Gateway?
• What is Apache APISIX?
• Features in brief
• Architectural Design (link to architectural design)
• Katacoda links and other tutorials
• Videos to get started with
• Link to contribute to the project (link to CONTRIBUTION.md in Apache APISIX repository)

Installing Section (partial)

• Prerequisites
• Different methods for installing Apache APISIX - RPM, DEB, Docker, Source Release
• Building from the source
• Stepwise procedures and solutions for possible traps and problems

Apache APISIX configuration (missing)

• What are the different types of configuration Apache APISIX needs?
• Description of fields and their examples
• List of supported/required Environment variables
• First party/third party extensions for configuration files(VS Code etc.)
• Custom configuration and how to add them
• Configuration examples
• Sample Project (in later stages)

Architectural Design (partial)

• Add a description to the diagram (current status: only diagrams no description)
• Remove configuration from this section
• Restructure this section to only contain architectural design
• Move definitions to "References" and if configuration then move to "Configuration"
  • Plugin
  • Service
  • Consumer
  • Router
  • Script
  • Upstream
  • Route

Plugins (need to be restructured)

• Introduction to Apache APISIX plugins
• How do they work?
• Getting started with plugins
• List of all plugins with links to their corresponding documentation
• Creating custom plugins
  • Prerequisites
  • How to create a custom plugin?

Miscellaneous (missing)

• Possible sections
  • Support + Community
  • Extra Features

Solution

Here is the proposal for a new structure for the APISIX documentation.

(Sorry for the bad quality image 😓 )

• Each checkbox represent a chapter/page
• Each bullet denotes must-contain or preferred headers in a page.

---

Checklist according to the proposal

• Welcome Page

  • Quick View
  • What is the latest in APISIX?
  • Featured
  • Changelogs

• Quickstart (APISIX in 5 mins)

  • Overview of APISIX
  • Setup and use APISIX right away

• Getting Started

  • Installation
    • From Package Managers
    • Docker Installation
    • Buiding from source
  • Contribution Guide link to: https://apisix.apache.org/docs/general/contributor-guide
    • How to contribute
    • Type of contributions
    • Opening new issue
    • Opening a pull request
    • Code style
    • Claim your goodies (Yes we have contributor's t-shirt 👕 )
  • Community Guide
    • Slack
    • Mailing Lists
    • Other communities
    • Community Efforts

• Learning Library

  • Learn APISIX
    • YouTube Video Links
    • Tutorial Links (Katacoda + Written)
  • Usecases / How to guides
    • Can be used for katacoda tutorials

• Concepts

  • Route
  • Plugin
  • Script
  • Service
  • Consumer
  • Upstream
  • Global Rule

• Configuration

  • Introduction and types of configurations
  • List of fields and configuration examples
  • Supported environment variables
  • Custom Configurations
  • Scripts
  • Debug Mode
  • Plugin Configuration

• Architectural Design

  • APISIX Architecture
  • Plugin Architecture
    • Plugin loading process
    • Plugin Hierarchy
    • External Plugin Architecture

• API

  • Admin API
    • Split the pages
  • Control API
    • Split the pages

• Plugins

  • Introduction to Apache APISIX plugin
  • List of all plugins with link to their description
    • One plugin per page
  • Plugin Developement
    • Setup Plugin Development Environement
      • Plugin Development Kit
    • Plugin Development Process
    • Writing Test Cases
    • Openresty/ngx_lua development guide (link if already exists)
  • External Plugins
  • Plugin configurations
  • Plugin Testing

• Integrations

  • What are integrations / extensions
  • Officially supported integrations/extensions
  • Community developed integrations / Third party plugins

• Miscellaneous

  • Support
    • Where to contact for help
    • Known issues and their solutions
    • How to report issue/bug
  • FAQ
  • Extra Features
    • Stand Alone Mode
    • Batch Processor
    • Add more here
  • Protocols
    • HTTP
    • GRPC
  • References
  • Heath Check

  ---

  Feel free to add missing parts, and DONOT mention this issue with closing keywords. This issue is strictly for discussion only.

  ---

  Currently this proposal is in the review phase, once approved by the community, you can pick up issues and start working on them

[tokers]

Could the description of 'external plugins' more deliberated? I think there could have several documents to introduce the way to write plugins in different languages.

[nfrankel]

It depends what you mean by "little introduction". I really dislike coming to a project I don't know, and being presented with the update of the latest versions, but not understanding what it is about.

Good examples:

• https://heron.apache.org/
• https://kafka.apache.org/
• https://apisix.apache.org/

[juzhiyuan]

Hi, Avinal,

Thanks for your new structure 🤗

1. Getting Started → Contribution Guide/Community Guide: How about linking to https://apisix.apache.org/docs/general/contributor-guide?
2. Usecases/How-to Guides: Are they the same contents?
3. API → AdminAPI: Will we split different entities into different sections?
4. Plugins → External Plugins: Just to make sure, do you mean Java/Go/xx Plugin Runner or plugins made by unofficial members? e.g https://github.com/swisscom/apisix-opa-plugin
5. Plugins: Many developers report that they cannot work well with Plugin Development in different machines/environments, could we have some recommended environments? or PDK (Plugin Development Kit, @tzssangglass is familiar with this).

Others LGTM, also cc @moonming @membphis to have a review, the new structure is important to us community and users.

[moonming]

@avinal great work 👍
Documentation is a part of Apache APISIX and is the most important part, looking forward to the new documentation structure

[shuaijinchao]

Great, in the new documentation structure, I see the logic of the documentation context and the process of helping users understand APISIX. Rather than feature points scattered across different documents like they are currently.

[tao12345666333]

👍 I think it's important to add "What is an API Gateway?"

[moonming]

We can add security, observability, Kubernetes deployment, multiple development language development plugins, WASM, etc. In the protocol part, MQTT and GraphQL are also worth mentioning.
Others LGTM

[leslie-tsang]

Would it be better to add a Concepts section to introduce route service consumer upstream ?

[juzhiyuan]

It depends what you mean by "little introduction". I really dislike coming to a project I don't know, and being presented with the update of the latest versions, but not understanding what it is about.

Good examples:

• https://heron.apache.org/
• https://kafka.apache.org/
• https://apisix.apache.org/

Agree 🤗 @avinal we could pick some parts from current resources? like README, blogs to describe Apache APISIX?

[fbartels]

A very nice initiative. When getting started with Apisix I found myself constantly switching between documentation and blog posts around specific topics. Looks like your proposed "use cases" chapter would combine this quite nicely.

[tzssangglass]

5. Plugins: Many developers report that they cannot work well with Plugin Development in different machines/environments, could we have some recommended environments? or PDK (Plugin Development Kit, @tzssangglass is familiar with this).

Perhaps a Plugin Development directory is needed to collect documentation related to plugin development.

under Plugin Development maybe:

1. Build development environment
2. Development Process
3. Development and debugging skills
4. Writing test cases

Now we have some documentation covering these.

This is a great proposal.

[tokers]

5. Plugins: Many developers report that they cannot work well with Plugin Development in different machines/environments, could we have some recommended environments? or PDK (Plugin Development Kit, @tzssangglass is familiar with this).

Perhaps a Plugin Development directory is needed to collect documentation related to plugin development.

under Plugin Development maybe:

1. Build development environment
2. Development Process
3. Development and debugging skills
4. Writing test cases

Now we have some documentation covering these.

This is a great proposal.

Besides these aspects, I hope that the below things can be added:

1. Guide about openresty/ngx_lua development (give some materials are also good);
2. Not only how to write case but also how to run them;
3. The Plugin Development Kit docs