Wiki vs GitHub Pages

[lpglinard]

This discussion item is related to #55.

[Cintyabio]

Wiki vs GitHub Pages: Features, When to Use Each, and Whether It Makes Sense for Us to Use Them — and Why

What is each one? When should you use them?

Both are repositories for documents, but Wiki is more limited and focused on documentation, while GitHub Pages can be used to host any type of file, such as web pages, portfolios, and more — not just documents.

Wiki is much simpler to set up and use, as it is geared solely toward documentation. It’s a great repository for documentation of small projects. Wiki is based on markdown features and can include any type of information about the project, from text to images or other types of files.

Pages offers more customization features. Application code updates are sent directly to Pages when you commit to the repository, and because of these features, its setup is a bit more complex. Larger projects will inevitably use Pages, as they require more space and resources.
To create a site on GitHub Pages, follow this step-by-step guide: https://docs.github.com/pt/pages/getting-started-with-github-pages/creating-a-github-pages-site

For performance reasons, wikis have a flexible limit of 5,000 files total, regardless of file type. If this limit is exceeded, users may not be able to access some pages. If a larger wiki is needed, it is recommended to use GitHub Pages.

Should we use it? Why?

Since our project has a smaller scope, it makes sense to use Wiki due to its simplicity in configuration. Unless the team is interested in using Pages for the experience and learning, we understand that it’s not the best fit for our application.

Wiki Example:

Page example:

https://square.github.io/

https://gist.github.com/Cintyabio/62deeaf5adb250b05d8793bd8fdebe90

[lpglinard]

Folks, take a loot at this IntelliJ plugin. I've used it to document part of research on software development. It is a great tool to write technical documentation.
https://www.jetbrains.com/help/writerside/getting-started.html

[lpglinard]

Hi team,

After our recent discussions and evaluation of the available options, we’ve decided to use GitHub Wiki as the documentation platform for this project.

Given the project's smaller scope, Wiki offers the simplicity and ease of setup we need, while still allowing us to organize and share relevant information effectively. Unless there's a specific need for more advanced customization or hosting features, Wiki should serve us well.

Thanks to everyone who contributed to the decision!

Best,
Lucas