GitHub wikis are not really wikis since they may only be edited by project members. They are much less visible to passers-by than the docs in the main repo. For small projects that often means they are the place where documentation goes to die.
I suggest moving all documentation into one place: the docs/ directory in main repo. That has the following advantages:
Anyone can suggest documentation enhancement via standard pull request
Docs are cloned along with the rest of the repo and are available offline
Docs are more visible to passers-by: the docs/ folder is right there on the first screen. Having "Wiki" link in the header is not the same - it does not mean the wiki is not empty, user has to click to learn that - and in most GitHub projects wiki is empty, so no one bothers clicking.
Docs are more visible to developers. They are right there in git workdir. git grep returns matches from both docs and the code at once. That means the docs will be less often forgotten and left out of sync.
Other people have spoken out in favor of this approach:
This pull request merges wiki contents (which was tracked in git repo behind the scenes) into docs/ - while preserving all edit history and author information.
GitHub Wiki should be disabled after this pull request is merged.
GitHub wikis are not really wikis since they may only be edited by project members. They are much less visible to passers-by than the docs in the main repo. For small projects that often means they are the place where documentation goes to die.
I suggest moving all documentation into one place: the
docs/directory in main repo. That has the following advantages:docs/folder is right there on the first screen. Having "Wiki" link in the header is not the same - it does not mean the wiki is not empty, user has to click to learn that - and in most GitHub projects wiki is empty, so no one bothers clicking.git grepreturns matches from both docs and the code at once. That means the docs will be less often forgotten and left out of sync.Other people have spoken out in favor of this approach:
This pull request merges wiki contents (which was tracked in git repo behind the scenes) into
docs/- while preserving all edit history and author information.GitHub Wiki should be disabled after this pull request is merged.