strogonoff
commented
3 years ago @ronaldtse, we’ve touched on this before—here’re my ideas about it (this looks like a good place to put them in writing).
Summary: (A) in short term, Aperis will add certain features that make sense for documentation but also (as a side-effect) for blog-like articles, (B) I think blogging-specific features shouldn’t be in Aperis, (C) we should streamline the process of creating a site that combines Aperis docs and a blog under the same umbrella.
Features that should make Aperis somewhat usable for blog-like content as a side-effect
- These features are needed for docs, but also allow to fit blog-like content in Aperis while dedicated blog plugin is in development:
- Docs pages should show creation/modification timestamps.
- Docs pages should support displaying contributors.
- Front page of the docs could show a block highlighting recent changes in featured documentation sections.
- These features primarily concern Aperis doc pages components and corresponding react-static plugin.
Why I believe full-blown blogging functionality shouldn’t be part of Aperis
- Blog and documentation have fundamentally different purposes and focus on different types of content.
- Documentation benefits from a different, more strictly specified content schema.
- Blog articles tend to be more freeform (strict schema will hinder authoring process), long form, and has different readability requirements.
- In fact, documentation should not use pages or “articles” as building blocks. Like a standard, documentation should consist of sections of various types, recomposable in different ways (as one big article, as an interlinked docset, and so on).
- Aperis is intended to be used as a documentation system.
- Instead of adding features that are tangential to documentation, Aperis should focus on deepening documentation focus.
- Documentation features in the works or planned later are:
- extended content schema;
- incorporating glossaries;
- versioned documentation:
- manual and eventually automatic notices “changed in version …”,
- displaying changelogs,
- using Git repository tags to generate browseable versions;
- including documentation from external repositories (e.g., software has docs in the same repo as source code, and Aperis allows to add it under a subpath on Aperis docs site);
- possibly supporting documentation auto-generated from documented or statically typed source code.
A website that consists of Aperis docs dataset and blog dataset
- In Paneron, a repository can contain multiple datasets.
- This means, one repository can contain an Aperis dataset and a blog dataset, and authors can use Paneron to manage either.
- Repo-wide CI workflow can build a single website from both datasets. (Aperis docs don’t have to start at the root of the site.)
- We don’t have a full-blown blogging extension working yet but we will.
ronaldtse
On the LutaML site (https://www.lutaml.org) we wish to let authors add blog posts. What's the best way to do that?