Thanks for the comment, resourceful stuff really. But it actually proves my point, in order to find "basic" information on creating a plugin you need to dig in the forums a lot.
The documentation is vague and pretty outdated..
Also I couldn't find how can I get access to the developer's forum. It says I should contact them, how do I do that? just PM one of the admins?
A better documentation would be something I still desperatly need. For every plugin I'm working on, I have to study Gardens source code and all the plugins I can get hold of. But I'm never sure if the example I'm looking at is a good or at least a full blown example or not.
All the documentation tools have to explain the framework on a file by file basis but that's not how things work in Garden. If I want to know if a user is allowed to do this and that, I have to know that there is an extra class for permissions. That's not obvious for me. So I would need an explanation that's showing me how to do things from an "objective" perspective.
Looking at Garden, I see 3 main points of interest:
1. Users
2. Threads
3. Messages
Whatever I do, it has something to do with one of those. There are subtopics, though.
Users
1.1 Permissions
1.2 Notifications
1.3 ...
Threads
2.1 Discussions
2.2 Comments
2.3 ...
Messages
3.1 ...
...
And maybe even subtopics of the subtopics, but I can not imagine any right now...
You would also need more general topics like database access, most used/important general functions and how to find all of them, the plugin mechanism, the way how modules work, etc.
To each of the topics I would like to have a description of what
purpose
parameters and
return values
each function has that a) influences or b) gives info about the topic.
Furthermore, there should be examples, examples, examples. Not only for the single function as such, but for the context in which that function could be used.
However I would say though it is a question of approach. That is where you are now. However a good API instructional helps you get into a frameworks. if you have a better idea of how the framework works then you can more readily help yourself.
Garden itself does not have full user function on its own. The dashboard, which has the dual purpose proto application and administration, has the user capability, building on core methods. Discussions, Comments, Messages these are all a functions of applications.
To me the by the far the most obvious approach to explain he framework initially, is by breaking down a single request going thought the index and dispatcher. You can start simply, and then build up all the main concepts of the framework and the applications by replaying this scenario.
It goes without saying that many web applications will have a userbase, so that is a fairly early concept you would introduce. Vanilla actually come after that, it is one application. However you can say early on, that you promise to cover it shortly.
These are the things that words alone would take too long to explain. For instance the parallel nature of the framework, and how the application inherit core an dashboard capability, and how plugin and themes and locales, enhance and extend that workign in parallel. So qualify graphic would help.
I would also like to make a distinction between a developer program and simply API documentation. In a developer program people are encouraged to sign up (metaphorically or literally) to the program, they are directly given the resources and tools to get them going, walked through it. It is also about the details, making sure it all makes sense from a noob perspective.
@Aviram said:
I have developed modules/plugins/addons for many platforms (Magento,Joomla,Opencart,etc).
The good news is that if you survived the horrible abortion called Magento, and could develop a plugin for the completely undocumented OpenCart, Vanilla will be a walk in the park!
@Aviram said:
To be honest using Magento and Opencart was fairly easy given the amount of examples you have from the community.
Magento had it's very alive IRC with very supportive community.
I did both myself and I had a completely opposite experience. OpenCart community has been terrible, and the platform's design was not much better (the vqMod itself is a terrible patch), while Magento has an overly complicated, bloated architecture that makes everybody cry. I developed my first, fully functional, Vanilla plugin in two weeks, second one in half a day. With Magento, it took me three months, then I refused to touch it ever again. As I said, Vanilla is a much better experience.
@UnderDog said:
x00 your wish is our command, but we need a site to work on. Website? Github?
Or would you like to talk tools, concepts?
Ultimately this is not going to get going without the vanilla team's involvement. There are too many thing integral to what they are doing and those details matter. It also requires some professional input like technical writers, and someone ultimately responsible to the developer program with that technical expertise.
It has to be official, as you couldn't run a developer program without official involvement to make it integral to their project.
Ultimately it is a business decision for them, and they will have personal preferences and decisions to make. I wouldn't say there is no role for the community but it need to be mandated, and probably incentivised. It needs a formal structure and standards.
Of course the community can help with idea on processed of in-line documentation, but that is one component only.
I mean if there are people that have the skill an experience in technical writing, making instructional videos, communicating ideas those are the kind of people that would be useful.
I have found people like myself, and many techies aren't necessarily the best. of course there are exceptions to the rule, and you do need the technical input as well, just communicated effectively.
The point I don't need this is not for me, but it would have been a turn off if I was inquiring at that stage, as I wouldn't have to time to waste on something I would have no idea would meet expectations, even if it claimed to.
I think there is potential there and it one of the more sketchy aspects. The more talent that is attracted, the more the capability for the framework is extended, the more versatile it becomes.
As long as the Vanilla staff does not see an added value of a structured documentation, they will not invest anything into it, I assume. Daily business, creating revenue, is always more important for a small to medium business, but you could not grow above a specific size, if you do not invest in infrastructure.
If they are happy with what they've reached and confident that there will always be someone accessible for new hires to teach them the basics and willing to invest the additional time needed for every new developer they hire, there will be no need for them to let their paid(!) employees do a job that has not been done by now and business was always working without a better documentation.
Their intention is not to build a great OS framework, that should become very well known, their intention is to make money with the hosted version.
Certainly I do not know what their intentions or wishes really are, but I've seen a lot of small companies and those where the things you always get to hear when it comes to some tasks that anybody knows are really important to do "when there's time enough to do it". But reality shows that there is never enough time.
It is really not meant as an offense in any way! All I want to point out is that I do not think that there will be an official documentation project and planning an independent documentation approach, should be made without planning any resources from Vanilla staff into it. Everything else will most probably fail. After all they decide their priorities and they will decide what is when important. Some documentation that would be nice to have some day, will not pay any bills...
I would help with documentation but my skills are not even good enough to provide you with qualified screenshots. But I could always read what you have written and tell you if it is understandable enough for noobs
Even wordpress does not make make money out of the OS software itself. However the OS software is a means to an end, it can be be a way to get decent exposure, attract talent, which ultimately drives revenue channels.
Listen I could say to client I suggest using vanilla, but they might look into an say well it doesn't seem to have a comprehensive program, or these people seemed had these issues, or this level of support is not there, etc. Happened before.
But I do agree, very few people are going to contribute masses of free time becuase there is very little free time. The future for OS is professional OS.
As I know for a fact it was their intention was to build an OS framework becuase they announced it, if it wasn't they wouldn't have released it as OS, but there were always going have a hosted version as a SaaS. this is not inconsistent with OS. it is pretty normal.
I'm sure they would want more plugins at a standard they can use on the host version to, and more contributors to the core, which they can apply to the hosted version.
They do have a balancing act new features over stability, and stuff like a developer program to attract talent.
@R_J said:
As long as the Vanilla staff does not see an added value of a structured documentation, they will not invest anything into it, I assume.
Whoa, let's stop right there. We haven't worked on roadmap features half as much as we wanted to in the last year, but docs is on that list. Let's not cast disingenuous aspersions because things are not being done in the order you want them done. We have a strategic interest in better docs to bring new developers up to speed quicker. That said, you can talk about it all you want, but it's not getting us there any faster to keep repeating what you want. Santa isn't bringing a documentation system. It's still gonna be a while longer.
Lincoln like I said I don't needed it for myself. I'm just pointing out and making some suggestions.
I don't know what your plan is after 2.1 is released officially. But I suggest, a pause to spend time on rounding off the all the rough edges, focusing on stuff like this too. it is really a tough call though I feel your pain.
I also think it can be difficult for programmer to convey these ideas alone. It does need the input from those great at this sort of communication.
Instructional videos that bridge the gap between marketing / information / documentation. I used the word screen cast but this can be misleading, I think those kind of screen capture walkarounds can be limited. I'm talking about a sleek, topological, illustrated overview of the system and framework. A good video can make and impression much faster then text, if they bother to read it at all.
API documentation that is consistent and referenceable.
I sure you are very good, no harm in consulting someone savvy in this sort of presentation, and borrowing heavily from those that have done it very well.
I think Adrian will eventually make new feature tutorial videos centered on the cloud platform features. I don't think anyone on staff has plans to make other video content. I was only talking about written docs.
Comments
@peregrine
Thanks for the comment, resourceful stuff really. But it actually proves my point, in order to find "basic" information on creating a plugin you need to dig in the forums a lot.
The documentation is vague and pretty outdated..
Also I couldn't find how can I get access to the developer's forum. It says I should contact them, how do I do that? just PM one of the admins?
A better documentation would be something I still desperatly need. For every plugin I'm working on, I have to study Gardens source code and all the plugins I can get hold of. But I'm never sure if the example I'm looking at is a good or at least a full blown example or not.
All the documentation tools have to explain the framework on a file by file basis but that's not how things work in Garden. If I want to know if a user is allowed to do this and that, I have to know that there is an extra class for permissions. That's not obvious for me. So I would need an explanation that's showing me how to do things from an "objective" perspective.
Looking at Garden, I see 3 main points of interest:
1. Users
2. Threads
3. Messages
Whatever I do, it has something to do with one of those. There are subtopics, though.
1.1 Permissions
1.2 Notifications
1.3 ...
2.1 Discussions
2.2 Comments
2.3 ...
3.1 ...
And maybe even subtopics of the subtopics, but I can not imagine any right now...
You would also need more general topics like database access, most used/important general functions and how to find all of them, the plugin mechanism, the way how modules work, etc.
To each of the topics I would like to have a description of what
each function has that a) influences or b) gives info about the topic.
Furthermore, there should be examples, examples, examples. Not only for the single function as such, but for the context in which that function could be used.
All valid points.
However I would say though it is a question of approach. That is where you are now. However a good API instructional helps you get into a frameworks. if you have a better idea of how the framework works then you can more readily help yourself.
Garden itself does not have full user function on its own. The dashboard, which has the dual purpose proto application and administration, has the user capability, building on core methods. Discussions, Comments, Messages these are all a functions of applications.
To me the by the far the most obvious approach to explain he framework initially, is by breaking down a single request going thought the index and dispatcher. You can start simply, and then build up all the main concepts of the framework and the applications by replaying this scenario.
It goes without saying that many web applications will have a userbase, so that is a fairly early concept you would introduce. Vanilla actually come after that, it is one application. However you can say early on, that you promise to cover it shortly.
These are the things that words alone would take too long to explain. For instance the parallel nature of the framework, and how the application inherit core an dashboard capability, and how plugin and themes and locales, enhance and extend that workign in parallel. So qualify graphic would help.
I would also like to make a distinction between a developer program and simply API documentation. In a developer program people are encouraged to sign up (metaphorically or literally) to the program, they are directly given the resources and tools to get them going, walked through it. It is also about the details, making sure it all makes sense from a noob perspective.
grep is your friend.
The good news is that if you survived the horrible abortion called Magento, and could develop a plugin for the completely undocumented OpenCart, Vanilla will be a walk in the park!
My shop | About Me
@businessdad
To be honest using Magento and Opencart was fairly easy given the amount of examples you have from the community.
Magento had it's very alive IRC with very supportive community.
I did both myself and I had a completely opposite experience. OpenCart community has been terrible, and the platform's design was not much better (the vqMod itself is a terrible patch), while Magento has an overly complicated, bloated architecture that makes everybody cry. I developed my first, fully functional, Vanilla plugin in two weeks, second one in half a day. With Magento, it took me three months, then I refused to touch it ever again. As I said, Vanilla is a much better experience.
My shop | About Me
@x00 your wish is our command, but we need a site to work on. Website? Github?
Or would you like to talk tools, concepts?
There was an error rendering this rich post.
Ultimately this is not going to get going without the vanilla team's involvement. There are too many thing integral to what they are doing and those details matter. It also requires some professional input like technical writers, and someone ultimately responsible to the developer program with that technical expertise.
It has to be official, as you couldn't run a developer program without official involvement to make it integral to their project.
Ultimately it is a business decision for them, and they will have personal preferences and decisions to make. I wouldn't say there is no role for the community but it need to be mandated, and probably incentivised. It needs a formal structure and standards.
Of course the community can help with idea on processed of in-line documentation, but that is one component only.
grep is your friend.
I mean if there are people that have the skill an experience in technical writing, making instructional videos, communicating ideas those are the kind of people that would be useful.
I have found people like myself, and many techies aren't necessarily the best. of course there are exceptions to the rule, and you do need the technical input as well, just communicated effectively.
grep is your friend.
The point I don't need this is not for me, but it would have been a turn off if I was inquiring at that stage, as I wouldn't have to time to waste on something I would have no idea would meet expectations, even if it claimed to.
I think there is potential there and it one of the more sketchy aspects. The more talent that is attracted, the more the capability for the framework is extended, the more versatile it becomes.
grep is your friend.
As long as the Vanilla staff does not see an added value of a structured documentation, they will not invest anything into it, I assume. Daily business, creating revenue, is always more important for a small to medium business, but you could not grow above a specific size, if you do not invest in infrastructure.
If they are happy with what they've reached and confident that there will always be someone accessible for new hires to teach them the basics and willing to invest the additional time needed for every new developer they hire, there will be no need for them to let their paid(!) employees do a job that has not been done by now and business was always working without a better documentation.
Their intention is not to build a great OS framework, that should become very well known, their intention is to make money with the hosted version.
Certainly I do not know what their intentions or wishes really are, but I've seen a lot of small companies and those where the things you always get to hear when it comes to some tasks that anybody knows are really important to do "when there's time enough to do it". But reality shows that there is never enough time.
It is really not meant as an offense in any way! All I want to point out is that I do not think that there will be an official documentation project and planning an independent documentation approach, should be made without planning any resources from Vanilla staff into it. Everything else will most probably fail. After all they decide their priorities and they will decide what is when important. Some documentation that would be nice to have some day, will not pay any bills...
I would help with documentation but my skills are not even good enough to provide you with qualified screenshots. But I could always read what you have written and tell you if it is understandable enough for noobs
Even wordpress does not make make money out of the OS software itself. However the OS software is a means to an end, it can be be a way to get decent exposure, attract talent, which ultimately drives revenue channels.
Listen I could say to client I suggest using vanilla, but they might look into an say well it doesn't seem to have a comprehensive program, or these people seemed had these issues, or this level of support is not there, etc. Happened before.
But I do agree, very few people are going to contribute masses of free time becuase there is very little free time. The future for OS is professional OS.
As I know for a fact it was their intention was to build an OS framework becuase they announced it, if it wasn't they wouldn't have released it as OS, but there were always going have a hosted version as a SaaS. this is not inconsistent with OS. it is pretty normal.
I'm sure they would want more plugins at a standard they can use on the host version to, and more contributors to the core, which they can apply to the hosted version.
They do have a balancing act new features over stability, and stuff like a developer program to attract talent.
grep is your friend.
Whoa, let's stop right there. We haven't worked on roadmap features half as much as we wanted to in the last year, but docs is on that list. Let's not cast disingenuous aspersions because things are not being done in the order you want them done. We have a strategic interest in better docs to bring new developers up to speed quicker. That said, you can talk about it all you want, but it's not getting us there any faster to keep repeating what you want. Santa isn't bringing a documentation system.
It's still gonna be a while longer.
Lincoln like I said I don't needed it for myself. I'm just pointing out and making some suggestions.
I don't know what your plan is after 2.1 is released officially. But I suggest, a pause to spend time on rounding off the all the rough edges, focusing on stuff like this too. it is really a tough call though I feel your pain.
I also think it can be difficult for programmer to convey these ideas alone. It does need the input from those great at this sort of communication.
grep is your friend.
There are two things being discussed
grep is your friend.
You have no idea how much I'd actually enjoy writing coherent docs / tutorials if I had the time. I need no encouragement.
I sure you are very good, no harm in consulting someone savvy in this sort of presentation, and borrowing heavily from those that have done it very well.
grep is your friend.
I think Adrian will eventually make new feature tutorial videos centered on the cloud platform features. I don't think anyone on staff has plans to make other video content. I was only talking about written docs.
There are many ways to shell a nut. These are some really good written codex.
As long as they are accessible, immediate, and the introduction easy to understand (to php developers).
I still think some sort of illustration or annotation would help, however this should be uncomplicated too.
grep is your friend.
I will admit this was a well-timed prod.
Things are underway.