Using GitHub as content management system for developer documentation website

[techframewirk]

The current developer documentation website is built using wordpress. The content management for the developer docs website should be possible through Github. All contents in the developer docs should be present in a Github repository as well. Any changes made to the content in Github should automatically reflect in the developer documentation website.
This would enable the review and addition of content to the developer docs website by the wider developer community. Anyone can raise issues to highlight problems in the content as well as make changes to them using pull requests. Also the user should also be able to suggest edits to content on the developer docs website which would raise a PR on Github. All features in the current developer docs website should be present in the new system as well.

We had a discussion to brainstorm solutions for the same. Sharing minutes of the meeting below :

• All content in developer docs website currently to be present in Github by 15th February 2022. UI can be perfected later as well.
• Vedant has suggested the use of Gatsby for the developer docs website.
• Here the content will be present in markdown format in one or multiple GitHub repositories. Multiple Github repositories will enable versioning of the information. Vedant has suggested the same can be done using a folder structure which will simplify the process. Vedant to look more into using Gatsby and the development required to enable all the features in the website.
• Will also be parallely checking if a plugin can be used to update the content on the Wordpress site whenever changes are pushed to a repository.
• Ved Prakash has suggested to use MKDocs for developer docs website.

[techframewirk]

Scope of changes

The document analyses the types of content currently available in the developer docs website. There could be more types of content added later on which may require updates to the process.

Expectations

The content management for the developer docs website should be possible through Github. All contents in the developer docs should be present in a Github repository as well. Any changes made to the content in Github should automatically reflect in the developer documentation website.

This would enable the review and addition of content to the developer docs website by the wider developer community. Anyone can raise issues to highlight problems in the content as well as make changes to them using pull requests.

Special predefined tags in the content can be used to specify how a type of content should be displayed or to provide metadata about the content.

All images or other content that is required for the site can be present in the folder assets in the root directory. The user should be able to link any of them in any of the documents.

The user should also be able to suggest edits to content on the developer docs website which would raise a PR on Github.

The developer docs should have a search bar, it should display popular contents, popular searches. 

Current Sections in website

There are the following main sections in the website:

• Overview

• Specification Reference

• Build with Beckn

• Projects

Overview

Collection of pages represented in markdown format

All pages in single level

Specification Reference

Transaction Layer Specification 

Collection of folders. Each folder can also have an index page which gives information about the folder. In case the index folder is not there just the contents of the folder in tree structure will be shown.

Core Specification

Core APIs

Schema Reference

Mobility Specification

API Reference

Schema Reference

Local Retail Specification

API Reference

Schema Reference

Logistics Specification

API Reference

Schema Reference

Infrastructure Layer Specification

Collection of folders. Each folder can also have an index page which gives information about the folder. In case the index folder is not there just the contents of the folder in tree structure will be shown.

Authentication

Registry API Reference

Build with beckn

Collection of pages with tags which are used for filtering. Each page should have metadata for tags which will be used for filtering.

Projects

Collection of pages in markdown with images.

All pages are on the same level.