lukasbestle
commented
3 years ago Thank you for your feedback! You are right that the README currently does not really make it clear from which idea the plugin originated and what the use case and workflow looks like.
I chose the name "Versions" and not "Git" because the Git part is just an implementation detail in the end. In my forum post about the plugin I tried to explain the reasoning and origin. Maybe that's even a good starting point for a better explanation in the README.
I will think about it again. :)
Maybe there is potential to make the setup shorter, but my technical knowledge of the plugin and PHP is too low.
Only the first two setup steps are really required, the remaining steps are for optional advanced features. I'm considering to move the docs to GitHub wiki pages to make the README shorter and increase the overview. Would that help?
Which aspect in the Versions plugin bothers you and why?
Documentation
How would you improve it?
Well, I don't know if it helps you. Maybe it's just me, so take it with a grain of salt.
I went half through the readme before I understood that I actually probably did not understand what the plugin does. I started with this mindset: I develop my sites locally, versioned with git. For the plugin, I'll therefore create a second git repository just holding the content and the plugin will store and version the content in this second repository with git, pushing and pulling changes on command.
Half through the documentation, I noticed, the plugin comes from another point of usage: You have your website on a server and you version content through git. Optionally, you can back up the content externally, but your main store for the content is the Kirby site on your remote server, where you initially install and setup the plugin.
The multisite content versioning (staging/production) assumes those environments are on the same server, to my understanding of the README.
What I therefore though the plugin is: Kind of an extended version of https://github.com/thathoff/kirby-git-content, but with version control that can be managed by content authors.
I don't know if this is me or the documentation, to be honest, but though, maybe it helps you.
So, I wonder, if either the feature list could be more clear, or if it needs a list of technical limitations, or if a visualization at the beginning of the README would make it clearer.
How would this make the Versions plugin better?
Maybe there is potential to make the setup shorter, but my technical knowledge of the plugin and PHP is too low.