Restructure tech docs

[tillprochaska]

Aleph’s technical documentation has been growing organically over the years. New information has been mostly added to existing pages, resulting in a few very long pages that are difficult to read and digest. This makes it difficult for authors/contributors to add new contents, and it makes it difficult for users to find relevant information.

This change reorganizes existing contents to make contents easier to discover, but I’ve also updated some of the frequently accessed contents and added new contents.

Preview

You can preview the changes here: https://aleph-docs-preview.netlify.app/developers/

Changes

#3064 has a complete overview of progress/changes, but below is a summary of the most relevant changes:

New

• Configuration option reference: A complete reference of all available configuration options (including those accepted by Aleph dependencies such as servicelayer). If I’ve missed any configuration options, let me know!
• Glossary: A reference of terms that have a specific meaning in Aleph.
• Explanation articles: In-depth articles about fundamental concepts in Aleph and Aleph’s system design (for example about the ingest pipeline, search, …)
• How-to guides: There’s a new section with How-to guides that help different types of users solve concrete problems. These are partially based on the existing FAQ as well as common questions we’ve received via our support channels. There are separate How-to subsections for developers, instance admins, and data journalists/developers.

Updated

• Data commons: Updated with new datasets and resources
• Development environment
• Production deployment: There is now a generic page about production deployments that lists a lot of things that admins should consider before deploying Aleph in production and a separate page that shows how to get started with a production deployment using Docker Compose.

Removed

• Memorious documentation: This page was outdated and is covered by the Memorious documentation.
• Deployment without Docker: This page was completely outdated. It’s not really an approach we can recommend, and updating it would be a significant amount of work.
• Importing structured data: This page covers many of the advanced FtM data mapping features with in-detail examples. I think it’s a great resource, and Pudo had some plans to migrate this page to the FollowTheMoney documentation. The basic concepts are covered by new How-to guides (like this one), but some advanced features are not.

Todos

• Fix GitHub Actions workflow
• Convert README to Markdown
• Evaluate Vale
• Update configuration options reference with new options that have been introduced in the meantime

Fixes #3064

[Rosencrantz]

Structure seems sensible to me, checked the test site and it's looking great. Giving this the thumbs up!

[stchris]

Love the rework, the structure makes a lot of sense to me. Thanks for all the hard work on this, @tillprochaska !

[stchris]

Just checking but the intention here is to leave it like this so we can update docs by merging to develop?

[tillprochaska]

Yes, good catch, this is indeed intended!

In order to publish documentation changes, they currently need to be merged directly into main (which is only possible if they do not contain non-docs changes). Merging documentation changes into develop means that they will only get published on the next release.

I think deploying docs from develop is sensible: In most cases, small changes will get published faster without us having to remember to merge to the (non-default) main branch. Also, this has sometimes caused merge conflicts in the past.

In case we really want to publish a documentation change only after the next stable release, this requires a little more work now, but this case is quite rate.