Improve the docs!

[pombredanne]

Hey, we need to up our game on the overall project docs and web site as I have received a lot of less positive feedback
Right now aboutcode.org is using wordpress and elementor
And the read the doc web sites are using Restructured text and Sphinx

The issues to me are:

• we can change the look and feel, but more importantly is the "architecture" of the information about the overall project and how to get started that is the most pressing issue
• we will need something that's based on text files in git repos, rather that wordpress which does not help much with participation

Inputs and suggestions and help are mucho welcomed. I am considering organizing a commando hackathon thing to get us started.

[pombredanne]

I think the key thing for me is we suck at "getting started", and we have many projects from data, to libraries, to low level tools, to command line apps, to web apps. Each of our users may have different concerns wrt. to getting help around each different tools to get started and get docs.

[pombredanne]

@adaaaam ping

[pombredanne]

Our page at https://github.com/aboutcode-org also is missing a lot of data and links.
We also have a lot of diagrams from slides and presentations that could be used to better explain all the things we do.

[DennisClark]

We need an AboutCode Overview document (and readthedocs format would work just fine) that answers the questions associated with actual use cases, and this doc (or a major part of it) would be organized as a list of those questions, such as:

• How do I use AboutCode to support CRA compliance in my company (enterprise) ?
• How do I use AboutCode to support CRA Compliance in my development team?
• How do I use AboutCode to find security vulnerabilities in my codebase?
• How do I use AboutCode to manage my security remediation tasks?
• How do I use AboutCode to create SBOMs for my products?
• How do I use AboutCode to consume (ingest) SBOMs from my suppliers?
• How do I use AboutCode to review my software products to ensure license compliance?
• How do I use AboutCode to communicate license policies and procedures to my team?

I am sure there are others, but those are the first that come to mind. I think that structuring/organizing a readthedocs that has a main TOC link for each of those questions would be a good way to get moving on an AboutCode documentation solution.

[pombredanne]

@DennisClark awesome. I will come up with more, focused on what I see from a developer point of view.

[pombredanne]

@Thatwriterjon ping... somewhat related, we are tracking upcoming blog posts ideas at https://github.com/aboutcode-org/www.aboutcode.org/issues

[pombredanne]

Also related is:

• Select a dev-friendly tool to publish the site and docs www.aboutcode.org#18

[pombredanne]

Here is a set of updated ideas for our TODO:

1. patch to ensure aboutcode.org has no dark corners and we can get started nicely
   1.1 ensure we have minimally correct readme and getting started
   1.2 Add PURL! which is conspicuously absent
   1.3 Make blog (and blog posts) visible https://aboutcode.org/blog/

2. move away from WP toward a file-based, git-based workflow
   2.1 Sphinx+Rst, Hugo, Docusaurus, Markdown/MYST?

3. harmonize all docs modeled after SCIO https://scancodeio.readthedocs.io

4. create persona-based, use-case based workflows for docs

5. create code, scripts, deployed demos, and packaging so that its takes under 5 minutes to try out any of our tools, libraries and apps.

6. Also create an org-wide glossary to support consistency:

• Create glossary/standard reference for terms/names used in or to describe products/services www.aboutcode.org#26

[pombredanne]

Moving this as an issue!