Easy for me to edit. I find some wysiwyg editors hard and/or time consuming to use. For myself, that is a big barrier to actually writing documentation.
Git based. Since I already have the code changes coming in through git, it makes a lot of sense to have a similar process for the documentation.
No authentication on my part. When I can pass the authentication chore off to git or github, I'd rather do that.
Looks good. There are too many good looking themes out in the world to put up with having something look bad.
Easy for other people to edit. I figure the more streamlined the process is for getting edits to documentation the more likely other people are to contribute to documentation.
I tried to use a wiki for documentation, but those that supported using git as a back end were old and didn't have a large following of users. I realized that I liked the way it was done for Home Assistant and saw that they were using Jekyll. It seems easy to understand and use, has lots of themes, and is extendable via ruby gems. There are already a number of extensions I'd like to use. It also has a docker container that supports live reloading. Sweet.
The downside is that the way Home Assistant deals with edits to their page is cumbersome and unintuitive for people not familiar with GitHub. However, there are some in browser markdown editors that I might be able to add some git or github hooks to. I think I could use github for authentication and git for creating and sending the pull request. Not a project I want to tackle right now, but it's one that might be worth it eventually.
My requirements for documentation:
I tried to use a wiki for documentation, but those that supported using git as a back end were old and didn't have a large following of users. I realized that I liked the way it was done for Home Assistant and saw that they were using Jekyll. It seems easy to understand and use, has lots of themes, and is extendable via ruby gems. There are already a number of extensions I'd like to use. It also has a docker container that supports live reloading. Sweet.
The downside is that the way Home Assistant deals with edits to their page is cumbersome and unintuitive for people not familiar with GitHub. However, there are some in browser markdown editors that I might be able to add some git or github hooks to. I think I could use github for authentication and git for creating and sending the pull request. Not a project I want to tackle right now, but it's one that might be worth it eventually.