Documentation / Developer Program / Codex
I have done ok with the documentation I don't need help, but much of time if I want to find something out I read the source directly, and search through it using command line tools. This is my primary first call and not the documentation, it saves time for me but isn't viable for everyone. I already have a good grounding of the architecture.
Bear in mind this is just my opinion, but I think it does carry some weight. I also understand there are lot of priorities so it is a question of balancing those, but personally I would suggest this is quite an important one, ahead of even USPs in upcoming versions. It is not newfangled or rocket science.
Vanilla has a business strategy of SaaS funded OS software which would ideally contribute back to the overall project.
The problem is the number of seasoned developers is still quite small. Typically the average developer here isn't that experienced and that makes a difference. Most people are tinkering, some are on their way to becoming seasoned developers, but have some way to go. More experienced developer would help.
Experienced developers will try and find the right platform which promises the right capabilities, but also has and easily referenced codex and developer program to make it worth their while. I would not be ashamed about borrowing heavily from how others are doing it. Even if you don't like the architecture that doesn't mean they won't have good idea, on how to do things, especially with mature projects.
I don't think I would have been attracted to Vanilla 2 had I not had encountered vanilla 1 first. It was the screen cast that sold it to me personalty. That was very good, I would do something like that again. it is good way of selling the product to web masters or developers who are not going to want to read through a lot of text initially.
The community wiki is well meaning but it catering to a different level. What is lacking is a consistent and professional codex, with developer program to go with it.
There is documentation, and developer help. But arguably it is bitty and informal. Given alternatives they may not wish to take a chance on Vanilla Garden, even if it might be better for them.
It is a quandary though becuase I realise that a developer program is a more of a full time operation. However working towards that goal would help.
grep is your friend.
Comments
What are you suggesting?
Are you asking for community produced screen casts? Are you looking for Vanilla Inc. sponsored stuff?
Could you link the video you watched about Vanilla 1?
Search first
Check out the Documentation! We are always looking for new content and pull requests.
Click on insightful, awesome, and funny reactions to thank community volunteers for their valuable posts.
What a great idea, I'm just figuring out how the codex would look like, which codex would we take as an example.
Should we generate it from a source documentation generator? Turn that into a Wiki? Markup? MarkDown? Subdomain for vanillaforums.org?
Use the Basic Pages application? Attach discussions to a generated 'wiki' page?
The way I would look at it (and I am by no means a real developer!) Is:
Create a basic application (see Vanilla Wiki), which problems do you run into? Is there a generated (BasicPages) Wiki Page about it or create one?
There was an error rendering this rich post.
It wouldn't really be like the wiki, completely different animal.
The codex would be documenting each method in context. I do think it does need supporting info and adequately describe the framework, personally I would do it from the POV of a request entering the dispatcher the travelling through to fetch the view or resource.
I would assume some knowledge of php development.
grep is your friend.
I don't know where it is now, it basically walk through the forum, explained the USPs and aproach, etc.
It that case it was more a quick promotional, but they could also be official guides through various aspects. Sometime heavy text is too much to take in until you know you are ready to invest in something.
grep is your friend.
Personally I think it shoudl be a professional effort. It can't be patchwork or bitty.
grep is your friend.
A developer program would be not necessary be providing direct support, but making sure all the APIs are well documented and there is some joined up thinking in the presentation,
In fact that is the key presentation and copy, and creating a recognised system that works going into he future.
grep is your friend.
....so Javadoc?
Something like this?
But focus on the technical aspects?
Search first
Check out the Documentation! We are always looking for new content and pull requests.
Click on insightful, awesome, and funny reactions to thank community volunteers for their valuable posts.
Like that but more topological overview of the whole framwork, then you can instructional on various aspects.
I think if you put a screencast on you front page it has to aim to impress. It has to sell it to you.
grep is your friend.
This sounds like something @Adrian needs to do
If I am understanding you, you are calling for a marketing/documentation effort to bring developers in?
Search first
Check out the Documentation! We are always looking for new content and pull requests.
Click on insightful, awesome, and funny reactions to thank community volunteers for their valuable posts.
The generator is less important, than having systems in place to update it consistently.
Personally I favour style that are descriptive but concise
array[string]string|boolis an array of string indexes and expects string or bool values.The generated code has to still present nicely, and have the associated documentation to go with it.
Basically what is needed is a technical writer/API writer to head this.
grep is your friend.
I think the best way to go about this is to look at existing software products and determine which ones provide the greatest appeal to developers and then replicate what they have done. This will provide us with a tested solution and a template to go by. I don't have much experience with other OS communities, but others may.
exactly.
grep is your friend.
You need Adrian for marketing, especially the initial pitch, but you need a technical writer to do the actual documentation or at least set it up.
grep is your friend.
The problem is people are goign to look at the second video an hold them to that pitch. Of course you can do all of those things, but it is made to sound like a cake walk. It is bit more rough and ready in reality.
That is one thing you have to be careful in marketing not to oversell yourself. So there has to be someone there to make sure it is all joined up and it is as smooth as possible, or at least the learning curve is explicit.
grep is your friend.
I see the problem though Vanilla team want to spend time creating a new spangled version, in order to provide more pull. But on the other hand you there need to be a balance with what is already there and the development capability that is a major component of the software.
The development capability is already there, but it is not accessible as it could be. it is not just just the documentation, but the documentation process is a good way of finding the part they maybe don't make the most sense or have been neglected.
The bittiness, can be a problem I think. Especially for people not like me, who haven't got a good idea of what is what.
grep is your friend.
.
There was an error rendering this rich post.
Hello guys, Vanilla newbie here.
I saw this topic and thought I should throw my opinion as a newcomer.
I think x00 is really right, I have developed modules/plugins/addons for many platforms (Magento,Joomla,Opencart,etc).
Right now I'm trying to develop my own plugin in Vanilla but I'm kinda lost, I've checked all of the documentation about plugins but none has really functions list, with documentation on how to use them etc.
I've been trying to read on other plugins but I have to say the syntax is much different then other OS projects I've saw.
Every plugin I try to comprehend just gives me more questions than answers.
Maybe there is API list for plugins but I really tried to search and the official documentation that is linked on top of page doesn't give me really all the methods I can use.
BTW I understand that Vanilla is less popular (I think) than Magento,Joomla,Opencart so of course it'd have less information around the internet but there are basic stuff that are missing.
@Aviram you are right, and the thing is it is really great system.
In fact I have considered creating and adapter class for wordpress so you can have the same implied hooks et all.
grep is your friend.
this might help you until another system is established.
http://vanillaforums.org/discussion/comment/195652/#Comment_195652
http://vanillaforums.org/discussion/23694/some-tips-i-learned-during-plugin-development
simplistic and a bit outdated....
http://vanillaforums.org/discussion/20359/annotated-plugin-how-to-write-a-plugin-for-how-to-set-guest-to-view-title-only-and-not-content
aside from that example plugin download as well.
and the wiki and the developer and tutorial categories.
I may not provide the completed solution you might desire, but I do try to provide honest suggestions to help you solve your issue.