Jekyll is a static site generator that takes a collection of content pages and assets, such as images, and generates a website. In an open-source project, it is natural to extend the prototypical README to a more extensive documentation of anything ranging from architecture, to design, to usage instructions, to user manual. A README is fine, but once it gets too long, it is best to structure it into folders by subject.
Full article