I have a private git repository hosted on bitbucket.org. There was also a separate wiki repository created automatically:
The wiki itself is actually a git repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
But, unfortunately, that doesn't make any sense to me. Whenever I update my source codes, in most cases I also have to update the documentation. And when I'm working on an old version of my source code, or in another branch, a future wiki would contain documentation, which isn't implemented in the current state.
Why not only creating a folder called "Documentation" inside my source code repository? So the documentation would always stay in sync with the current source code/API.
Aren't these wikis designed for documentation and should only be used as a simple replacement for a general projects homepage? For example: Info's about the developers, the projects history, it's purposed targets, and so on.
Aren't these wikis designed for documentation and should only be used as a simple replacement for a general projects homepage? For example: Info's about the developers, the projects history, it's purposed targets, and so on.
Not necessarily. As a commenter points out above, there are many possibly uses for such a wiki.
One good reason not to have the wiki as part of your repository is that any wiki changes (there may be many of these, possibly by non-technical users) would create commits in your project's history. This is often undesirable, as it distracts from code commits, can complicate merges, etc.
If you want to have a wiki-like directory in your repository there is nothing stopping you:
+ Documentation/
|--- index.md
`--- other-file.md
Changes to this directory can, of course, be synchronized with code changes.
There are other interesting approaches as well.
For example, on GitHub you can create a website from a branch gh-pages in your repository. This website will be automatically updated each time you update your branch, letting you keep your site somewhat synchronized with your code and also giving you nicely-formatted output and keeping the flexibility of a completely disconnected approach.
Use whatever works for you.