What are the main functionality differences between Github Wiki and Readme,

Question

What are the main functionality differences between Github Wiki and Readme,

Asking those that have used both readme and wikis extensively. So that we can better decide which to use for the purpose of outputing verbal information. This would be based on your answer. Thanks.

As examples, some have used wikis --

http://github.com/mbostock/d3/wiki
http://github.com/ParticleCore/Particle/wiki/Features

and some people have used readmes --

http://gist.github.com/atcuno/3425484ac5cce5298932

no better place to ask? -- meta.stackexchange.com/questions/157888/what-site-is-good-for-github-questions

Wheelbarrow

Readme mostly means important text that should be read regarding the program or software, or simply contains a summary of it. While Wiki is more like a documentation or manual on that software. So a Readme may or may not contain documentation, it can also come down to personal preference. With that in mind, this isn't really a programming question. – Innutrition

the readme and wikis are being used for the same purposes (providing information) as shown in the examples. im mainly asking about functionality – Wheelbarrow

Answer 1

Talking about a project repository :

• Readme.md is the packaging
• wiki pages is made for development/contributors documentation
• gh-pages branch hosts user documentation

Decaliter

i've just decided to go with wikis as most uses them, so wikis probably have more functionality (formatting, graphs, etc.), i'll find my answer eventually.... – Wheelbarrow

I like your answer but do you have any reference for this? – Velez

this is a great way of defining the boundaries between this apparently overlapping toosl – Bortman

Answer 2

Both readme & wiki have no function, except for providing information. Github recommends you to create a README.md to display a short summary & usage of your repository, while the Wiki is totally optional.

Coolant

what i mean is formatting options, links, graphs, and everything else they do, etc. (that's what i mean by 'functionality' - not sure what's a better word to use) – Wheelbarrow

Answer 3

I have to cross this bridge today, and in addition to this helpful thread I also found reading up the following helpful

• https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis
• https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

A key excerpt from there that I found useful and to the point

A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis.

Based on those and the other answers here, it makes sense to be high level in the readme along with all the getting started information (i.e. local setup), and leave the long form information such as application features, design principles, etc. in the wiki.

Another major difference of course is that the readme will get versioned whereas the wiki will not. Versioning of this doc is not a major concern for us, but it could be for you!

Monospermous

I like this answer, but just to clarify that the wikis do get versioned as well. There's a revision history at the top of the wiki pages and the documentation shows that the history is even stored in Git but it's a separate kind of sub-repo from your main repo (where if you're working on your-repo.git then the wiki is at your-repo.wiki.git according to those docs). – Climax

Thanks @bryant, you are of course 100% right. – Monospermous