citusdata / citusdata/activerecord-multi-tenant

Documentation is difficult to maintain

Open
#237 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Ruby
Stars
759
Forks
113
PR merge metrics
No merged PRs in 30d

Description

There are a number of HTML documents under git control under `docs/`.
Regenerating these shows that they have numerous diffs and are not well maintained.

```
cd docs
make build-docs
git diff HEAD | wc -l
4653
```

In my opinion, there is no need to keep HTML documents under git control.
I think it would be better to keep only the `.rst` files under git control and build the generated HTML during the release process.

I am not familiar with the release process for this gem, so I am not sure if this opinion is nice.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start in docs/ by running `make build-docs` and reviewing the generated HTML diffs against the tracked .rst sources. Then trace the gem's release process to determine whether HTML can be generated there; done means the tracked generated documents are no longer needed while documentation remains reproducible.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.