fish-shell / fish-shell/fish-shell
Documentation should be in main fish repo
- Dominant language
- Rust
- Stars
- 34.2k
- Forks
- 2.4k
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 13
Description
At the moment, documentation is present at several locations:
- `doc_src`, mainly for user documentation
- the `*.rst` files in the repo root
- `doc_internal` (mostly about porting fish to Rust, which is done now)
- the GitHub Wiki
- maybe more spots I've missed?
This can make it non-straightforward to know where to look for documentation, or where to add new docs. Within the repo, one can at least try to grep for potentially relevant content, but anything in the wiki will be missed by that approach. I consider the wiki particularly problematic, not only because it's not greppable (unless one remembers that it exists and has a clone of the wiki repo), but also because it's much easier to forget changing docs which are not in the main repo. Getting the appropriate documentation for older versions of the code is much more annoying if a separate repo with docs has to be handled in parallel.
At the moment, the wiki is also writable by anyone, which can easily result in undesirable consequences, like people adding links to malware (which happened e.g. on the Vundle.vim wiki (https://github.com/orgs/community/discussions/48173#discussioncomment-5094465)), or just spam/defacement.
Contributor guide
Assessment
This issue has not been assessed yet.