For a basic user; someone who is content to download openkore_ready.zip or, maybe even go so far as to check it out of SVN; the documentation is rich and accessible and there is plenty of support for it (disregarding some people who take offense at people asking support questions). On the wiki, almost each and every element of the config files is documented and from a front-end perspective it is the only resource you need to get a bot up and running and keep it that way. This is the basic functionality of Openkore. It works great.
This is for a User. This is from the perspective of someone who is having a service provided to them.
Then comes the moment where there is something that a user wants to accomplish that is not covered by the core functionality of Openkore. The user is presented with a number of options:
Find a macro that does what you want.
Make a macro that does what you want.
Find a plugin that does what you want.
Make a plugin that does what you want.
Fix the core functionality of Openkore itself.
This is where the difference between being a user and a contributor is determined. If a macro or a plugin already exists that performs the function you want to accomplish then the user can carry on their merry way and be happy about life and everything will be dandy. If however; the macro or plugin does not exist (as it probably doesn't (Going into the issue of 'sharing' on Openkore is a whole 'nother topic)) then the list becomes smaller:
Make a macro that does what you want.
Make a plugin that does what you want.
Fix the core functionality of Openkore itself.
Let's take a quick look at this from a user perspective:
A user probably doesn't know perl. For a user, the concept of cracking open the program and prodding around at the insides in an attempt to add functionality to the program is not even something that crosses the mind. It's out of the question. Fix the core functionality of Openkore itself is out before it was even in. The idea of making a plugin is not considered because it is not supported by the Openkore community. Look at the majority of "Help: How do I do X?" threads in the forum history (I've checked) and the default response answer to many questions is just "Make a Macro."
This makes sense from a user perspective too. Is there documentation that will explain to a user how to make a macro? Yes. Does it explain it in absolute basic terms that a user could understand? Yes. Does it talk through every possible element to produce a series of building blocks and examples that can be combined together, so no matter what you want to achieve you can probably figure it out by reading said documentation? ... Yes!
In the case of plugins: Is there documentation that will explain to a user how to make a plugin? Yes. Does it explain it in absolute basic terms that a user could understand? No. In fact it seems to be written for someone who already understands perl, rather than a user who might be looking at using this as a basis to start learning perl in order to develop plugins (I speak from experience. As someone who read that page knowing no programming but intending to learn; I found it hard to follow, confusing, incomplete and it almost put me off the idea of wanting to write plugins). Does it talk through every possible element to produce a series of building blocks and examples that can be combined together, so no matter what you want to achieve you can probably figure it out by reading said documentation? Well... No again. But this time there's no real fault. Plugins are perl and perl is a programming language. It is huge and complex and documented elsewhere anyway. Nobody expects this as an answer but I'll come back to it as a point.
This is where the User Interest Black Hole sits. It is the point between being a user and a contributor, nestled right between the choices of Make a Macro and Make a Plugin. The documentation drops off entirely and disappears, replaced by the roadblock of requiring knowledge of a programming language. All the support disappears and if a user wants to continue; develop and become a contributor, then they better go the hell away and learn a programming language and figure it out on their own.
Now going back to my previous point about learning perl. That's fine. There are plenty of great beginner resources out there for a user to go away and start trying to learn perl. Like this, and this. A user, with a bit of time and willingness could go away and learn, then come back with the intention of a) writing a plugin or b) fixing a core functionality.
Then comes a bigger problem:
Openkore on the inside is huge and unruly and confusing to a beginner. Of course it would be. It's a complex program that does a lot of things. So for a user who wants to start writing a plugin, there is no direction for where to start. There IS documentation, in src/doc/srcdoc, which is lean and bare and stripped from the comments of the source code. If you're going to start somewhere it's as good a place as any if you know it is there and you can find it (which I imagine many people don't know it exists). Then when you do get through the docs, it is vague and there are no descriptions. These Openkore functions should be the building blocks for creating plugins, but there is no real description of how they can be applied.
There are topics stuck to the top of this forum that desperately ask users to leech less and contribute more; that preach about the declining state of the Openkore community and I think one of the pinpoints of that problem is the steepness of difficulty between being a user and a contributor.
As I said at the beginning, I'm not asking for anything and I'm not proposing any solutions. I just thought this might be an interesting discussion topic for people. Users and developers alike. So to finish off quite a long topic; here are a couple of questions:
Users, do you feel like you want to contribute more to Openkore development but feel that you aren't able to because of this steep learning curve, and what do you think would make it easier to get over that hump? (i.e Source code documentation; Simpler, better commented plugins.)
Developers and those who have an understanding of Openkore's source code, would you be willing to expand on the documentation that is presented in src/doc/srcdoc with examples of how these functions can be applied, if you felt it would help more people become contributors to Openkore?
Finally, I would like to quote something that harvest said on IRC:
That is true and fair enough. I guess what I am saying is that there is a sudden wall to climb in the natural progression of user -> contributor.[17:34] <harvest> I don't think such a featurefull and unmanaged project can naturally be navigatable and easy for absolute beginners
Download OK -> Configure OK -> Run OK -> Use a Macro -> Make a Macro -> Black Hole -> Plugins -> Development
What are your thoughts?
