search

null-open-security-community / null-cms-website

null Content Management System
MIT License
0 stars 0 forks source link

[RFC] Proposal for null Content Management System #1

Open abhisek opened 1 year ago

abhisek commented 1 year ago

Problem

The current null portal at https://null.community is powered by Swachalit which designed primarily as an event management and automation system. It is NOT designed for content management, hence it causes friction and blocker when being used to manage content.

Goal

Adopt a technology to ease development, management and publishing of content for null community. The content may include

  1. Guidelines / Information about null Community
  2. Projects
  3. Research Papers
  4. Community Connect (Communication mediums)
  5. Etc.

Refer to null Documentation Project for some of the content created by the community so far.

Design goal for this system includes specifically:

  1. (Content) Developer Experience as a first class citizen with minimum friction
  2. Anyone can contribute but only maintainer approved content is published to null contents website
  3. Low cost hosting and delivery at scale
  4. Support static content including rich text, binary contents (images, uploaded files) and optionally dynamic content through JS
  5. Encourage DRY by leveraging structured data files (JSON/YAML) or remote sources (REST API)

Proposed Solution

Adopt a static content management (website generator) based on markdown and related content such as hugo or alternatives with GitOps as the change and release management workflow.

Content Guidelines

Refer to Diátaxis as a framework for technical documentation. In this line, any content can be categorized into one of the following

  1. Tutorial
  2. How-to
  3. Reference
  4. Explanation

While this categories may appear as a limitation of the type of content that can be published, in reality content can be categorized within these broad categories. This model will also bring some sanity and coherence in the type of content published.

Any content developed must have an associated tag to identify the category of the content.

Don't Repeat Yourself

If there are any page that publishes extendable lists such as member list, project list etc. then instead of creating markdown tables or repeating content, consider separating the data from rendering concerns. For example, the data can be defined in a structure file such as members.json or members.yaml and the members.md page can refer to the data to uniformly render the list. This makes it easy to add a new item.

Note: Consider the case where such data may come from a remote REST API e.g. Swachalit

Content Structure

- Index / Root
- docs
  - projects
    - Tools Catalogue
    - Project2
    - Project3
  - about-null
    - About Null
    - How to Join the Community
    - How to Start a Chapter
  - Events (Link to swachalit)
  - Community Connect
    - Discord Information
    - Google Group (Mailing list information)

The above structure is for content management only and not for visualization.

Content Website Generation

Generate a browseable and aesthetically pleasing (or not) website using a static website generator tool based on the document source of truth.

Change Management

  1. main is the central branch and will be configured as protected and will be the single source of truth
  2. Maintainers can merge a PR in main after 1 approval
  3. Leverage Teams and CODEOWNERS for managing maintainers and auto-assigning PR to the maintainer team
  4. Adopt Fork and Pull Request Workflow for contributions
  5. Implement appropriate CI action for PR correctness verification

Release Management

Technology Choice

Options

Static Website Generator

CI/CD

Content Hosting and Delivery

Way Forward

madhuakula commented 1 year ago

Thank you so much for the detailed write up @abhisek, I believe there are many tasks here than one as you described. What do you think would be the next steps. I believe we can start creating a project tasks and do a PoC with Docusaurus and Hugo with other solutions.

anantshri commented 1 year ago

How about using github pages itself. The entire flow can be managed in github via issues and workflows. We can have reviewers review and approve content also. hugo or jekyll all options will be open.

If writers give markdown content insite review will work via issue review. for PDF we will need off site review (as annotations might not work with github)

blog.null.community is right now working on github pages via https://github.com/null-open-security-community/null-open-security-community.github.io

madhuakula commented 1 year ago

That works cool.

I feel Docusaurus, MkDocs, Hugo, Jekyll, etc. is a big thing to choose and experiment as each one has different use cases and we wanted to ensure if that fits our use cases and support for future (Ex: Can some one help with extending, support, writing custom, etc.). Adding some details here for more https://jamstack.org/generators. But defining what we need, future direction would be helpful when picking as @abhisek mentioned. I think PoC would be great start I believe.

abhisek commented 1 year ago

Thanks @madhuakula @anantshri for the suggestions.

I do agree that there are some work to do to make an informed decision about the various static CMS generator tooling / frameworks available. I would consider following key personas for the CMS:

  1. Content Writer (Markdown)
  2. UI Developer (CSS, Javascript, HTML layouts etc.)
  3. Data Producers (can be static JSON, external API etc.)

As long as the tool / framework provides reasonable separation of concern for [1] and [2] and have an ability to consume and render externalised data (JSON is fine) then I believe we are good.

By externalised data, I mean something like this: https://github.com/covid19india/covid19india-react/tree/master/public/projected_maps

This data can be built and made available as static files through CI/CD process or (even better) can be pulled using XHR from some API but not absolutely required. This requirement comes from the thought that this CMS may eventually replace Swachalit as the main portal while keeping Swachalit as a backend data source only.

@void-null @pankajmouriya Can someone from the community do a POC / survey of the various CMS tools mentioned in https://jamstack.org/generators/ and identify a few choices that meet our requirement and also easy to use?

void-null commented 1 year ago

@abhisek We will try to find out volunteer for the same.

sameepshukla commented 1 year ago

Hello @abhisek I was assigned to do a survey of various CMS tools mentioned in https://jamstack.org/generators/ and I found out that we can go with Jekyll or Hugo Jekyll and Hugo both support the key personas mentioned.

talking about headless CMS Cockpit could be good option as it uses APIs and JSON to deliver and present content, and it's both language and database agnostic. It is open source and support all site generators .