trixi-framework / trixi-framework/Trixi.jl

Create a dedicated repository for binary documentation assets?

Open
#194 4 comments 0 reactions 0 assignees View on GitHub
documentation good first issue
Dominant language
Julia
Stars
731
Forks
166
Avg merge
2d 18h
Merged PRs (30d)
25

Description

In light of issues such as #169, I wonder if we should establish a way to store binary blobs (aka image files) that we want to use in the documentation. Right now, we already use 2-3 images in the [README.md](../blob/master/README.md) and the docs, but each time I consider adding a new one I feel slightly bad about permanently increasing the repo size by 50-100 KiB. This is exacerbated by the fact that images, just like other documentation, often become outdated very fast and need to be replace regularly.

One possible solution could be to have a dedicated repository to store documentation assets such as images or videos, e.g., `trixi-framework/documentation-assets`, that we allow to grow in size over time. A different approach could be to store binary assets in a dedicated *branch* within the main repo, which gets regularly purged by deleting its history (however, this would raise the question of if and how docs for older releases should be kept alive).

Another thought (although slightly orthogonal to the main question here), is whether it would be beneficial to have a dedicated repository to host the documentation, such as `Oceananigans.jl` does it with [OceananigansDocumentation](https://github.com/CliMA/OceananigansDocumentation).

Contributor guide

Open the contributing guide

Research direction

Review README.md and the current documentation image references, then read issue #169 for related context. Compare the proposed dedicated repository, a dedicated branch, and a separate documentation repository, including how existing and older-release assets would be preserved; done means reaching and recording a clear project decision.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.