1.5 tutorials, good starting point?

[AmyStephen]

That is *perfect*, Scott. I'll hook it in. Thanks very much!

Amy

[seadap]

Wow Amy!  You work fast!  I'm impressed!

And just for the record, it's not J!code but rather Eclipse PDT. 

[AmyStephen]

Oh! I missed that point. Hm... I had understood the J! devs (Louis) were hopeful we'd go with JCode. I probably missed the discussion or we will be offering choices? Sorry, Scott, I feel out of the loop on this, I'm afraid. 

It's not a problem for the wiki, though, I'll update accordingly and we'll continue to figure things out, if necessary.

Thanks much!
Amy

[seadap]

I tried to get J!Code to work but the plugin for Xdebug wouldn't play nice.  J!Code is just Eclipse with some plugins already installed.  I'm using Eclipse with PDT because it works with Xdebug.  It's essentially all the same but with different plug ins.  J!Code is based on an older version of Eclipse so it has some bugs.

I would prefer to use J!Code and intend to update the wiki once the developers get J!Code updated.

EDIT: The article can be found here.

[seadap]

Amy,

Do you think we should move the outline to another page and use the intro page to give and introduction and link index to the rest of the articles?

If one follows the path Documentation Wiki -> Joomla development for beginners they get the outline with no other reference to the other articles we've created.

[AmyStephen]

Makes *perfect* sense on the IDE - thanks for explaining that for me!

Regarding your second question, do you mean have the first page present a table of contents that links to each and every page of the course? If so, that sounds good to me and makes sense. Let me try something and see what you think.

I keep get interrupted with phone calls and family, hehe. What I need to do is finish posting the pages, then perhaps you might want to go through it the second time and help solidify the outline.

Then, we can start handing out the work!
Amy

[seadap]

....Work????  I thought this was play!!!

Regarding your second question, do you mean have the first page present a table of contents that links to each and every page of the course? If so, that sounds good to me and makes sense. Let me try something and see what you think.

Well, we definately should for the course work but also for the other articles that we write for example:

• Outline
• Course

•   Topic 1
•   Topic 2

• IDE setup and configuration

etc...

[AmyStephen]

Agreed. I am so happy we have you on the team! Love your positive attitude and excellent work ethic.

+++

Feedback on the IDE page:

- Consider starting with heading 1 (seven equal signs) - that way your outline will not be pushed to the right so far. Since you are on your own page, you can have heading 1 for that section. I'll do the same (unless you object) and we will have consistency on each page.

- I am not certain of this one, but I'll toss it at you, anyway. There are 13 steps. I wonder if it would help understanding if you broke it into five major steps, with substeps, like follows:

XAMPP Installation - Steps 1 - 3
IDE Installation - Steps 4 - 6
Debugging Configuration - Steps 7 - 10
PHP Project Configuration - Steps 11 - 12
Plugin Installation - Step 13

- For your code examples, like phpinfo(), you could this stuff in here or stuff in here for formatting.

Just some ideas - it is looking really good!
Amy

[seadap]

DOH!

I forgot to put the images in too!

I'm not sure I know what you meant by the heading changes.  Have a look and see if I got it right.  I like the idea of having a consistent look for all the articles.

I liked your sub-section idea and your code sample idea too.  I'm not very adept at developing wiki pages so your help is greatly appreciated!

[AmyStephen]

Love it! The images really help, too. The only change I'd make is removing the (Steps 1-3) thing - that was just for you. Otherwise, it's looking very good and I'll test it when I'm done.

Thanks again!
Amy

[AmyStephen]

Question(s) for the group - jbruni, Chris and Ian, too:

I am on "week 3" putting the outline into the wiki. And, it's very obvious to me that there are a TON of classes in Joomla!

As we all know, jbruni has done a FABULOUS job of documenting JObject. This will be VERY useful to beginners to learn how to navigate the existing documentation and begin using these powerful classes.

He has also worked through JObserver and JObservable in the base package.

OK - I am nearing a question! 

I believe the classes and packages need to be documented for "regular documentation", too. (Ian - Chris?)

And, I think it's probably too much to think we would have this level of rich documentation for each and every class for the Beginner's guide.

So, is it enough to have a few classes documented to show beginners HOW to use the material and navigate the information available, and then focus on finishing the documentation needed for the Dev Doc Team. The beginners guide could point to that material, as well.

jbruni - what do you think? How did you envision finally being done with this work? hehe!

Chris and Ian - what work does the doc team need to do in that area? How do you see jbruni's brilliance most useful to the community?

Everyone - What do you think is needed for the beginner curriculum?

Thanks!
Amy

[seadap]

My 2cents:

Give a man a fish, feed him for a day.

Teach a man to fish, feed him for a lifetime.


Otherwise said:

Give a man a match, warm him for a moment

Light a man on fire, warm him for the rest of his life!

[bascherz]

I rather envisioned our "courses" describing how to get setup to do Joomla development (which is well along its way) and provide the basics for writing each type of extension. There were some very simple examples of a module, mambot, and component presented for version 1.0. We need that level of detail and more, with references to the API and to other reference material where necessary. The folks who come to read the "jbeginner" wiki will want to get started quickly and cleanly. Once we have that framework in place, we can expand upon it. We should probably not be mapping out too much detail just yet. We should focus on the basics first so that there can be utility in our work sooner rather than later.

So, there's MY two cents.

[AmyStephen]

Light a man on fire, warm him for the rest of his life!

Wouldn't that burn him out? hehe!

OK. That doesn't help me specifically enough. Out with it! What do you think we should do for week 3?

[AmyStephen]

I rather envisioned our "courses" describing how to get setup to do Joomla development (which is well along its way) and provide the basics for writing each type of extension. There were some very simple examples of a module, mambot, and component presented for version 1.0. We need that level of detail and more, with references to the API and to other reference material where necessary. The folks who come to read the "jbeginner" wiki will want to get started quickly and cleanly. Once we have that framework in place, we can expand upon it. We should probably not be mapping out too much detail just yet. We should focus on the basics first so that there can be utility in our work sooner rather than later.

So, there's MY two cents.

So, would you say, then, that showing JObject - so that new learners know how to read the documentation - is enough for the Beginner's class. Then, focus on the Dev Team Documentation effort to fill out the "normal" documentation?

Meanwhile, in the beginner's class, go on with module, component and plugin - then onto MVC?

[seadap]

Okay, if I must...

I think it would be helpful to have a course on the basics of the J! framework.  Explain what MVC is and how it's used.  Another lesson (or series) should be about how to navigate the API docs.

Building on these two ideas, provide some sample work for bots, mods, and components.

Once this foundation is laid, more advanced topics could be covered such as how to convert existing 1.x components to 1.5x etc.

I haven't read through your outline yet Amy so I may or may not be in sync with what you have in mind.

[AmyStephen]

@scott - that helps, thanks!

++++

@bascherz

Components, modules, and plug-ins (which replace mambots in J!1.5) are unique in what each does.

A content plug-in, for instance, essentially gets called by the core code when articles are displayed and has the opportunity to search for special text strings processed specifically by that plug-in and replace them with other text. For example, a plugin might process the string {avatar} and insert the avatar uploaded or selected by a user on a site equipped with Community Builder or replace {video=path-to-video} with streamed video content. An editor plug-in can completely define or extend an existing content text editor (e.g., JCE).

A module is simply something that can be inserted into your site template and appear on your pages. Modules can be instantiated, often multiple times each, and each instance can be placed at a specific position on the page. Positions can be made to appear only when certain menu items are selected. Some example modules are login, online users, visit counter, and Newsflash.

The admin interface for modules and plug-ins is completely coded in XML, so there is no dynamic element to it and no real way to customize the look and feel of the parameter input part.

A component is the most elaborate and complex type of J! extension. It can have both front end (user) and back end (admin) capabilities, and can be made to do many different things. Components can have one or more ways to have capabilities inserted as items in site menus, and the admin interface can be as elaborate as the author chooses it to be. Some examples include photo galleries, discussion forums, and guest books.

Rules of thumb:

Modules - data already exists and you just want a new way to present it on your site
Plug-ins - data, content, or custom functions replace information in articles or functions extend core features
Components - add custom functions to your site that can be selected from menus

@Bascherz - would you be willing to add this information to the Wiki in a topic entitled What are Modules, Components and Plugins? It is referenced in Week 3 on the Wiki in the Beginner's course.

Do you have an ID? If not, we need Ian to hook you up.

Thanks!
Amy

[bascherz]

Though I think the wonderful detail being explained on the J!Object and other core code is very valuable, I don't know if it's absolutely necessary to know it in so much detail just to get started. I would actually consider that more of an advanced level of instruction. Explaining the entire API at that level of detail would take quite a long time, and I don't know if it really has as much value as a starting point as it will once developers get to the point that they really need to know what's going on inside the core. I also believe the detail that has been written on those few core elements might better be done in the API documentation, although I am pretty sure that wiki gets populated directly from the core code.

I dunno...it almost seems to me as if we are trying to become experts on some of these topics right off the bat. Maybe I am just missing the whole point of this effort.

I have my ID and logged in and changed my password. Subsequently, I received a repeat of the original email providing my login credentials. I haven't tried logging in since I got the second email, but I will figure it out.

I would be willing to elaborate on the topics you quoted me as having addressed in a prior post, Amy. However, I have not written any 1.5 extensions yet. I have written 1.0 content mambots, CB plug-ins, modules, and one component. To do justice to the section you mentioned, I will have to learn the 1.5 way of doing things. But I am willing to do it. Been away all weekend (driving mostly), so I haven't had the opportunity to start yet.

EDIT: Basically, I agree with Scott. Understanding the MVC concept and basic J! framework are important and the right level to start.

[AmyStephen]

I'll let others contribute to the curriculum discussion question and see what comes from the group.

+++

Regarding the module, component, plugin documentation - I believe what I quoted you on is perfect. That's a short intro to explain the difference. More than that or deeper than that would not be necessary, IMO.

No hurry, either. So no worries!

Amy

[AmyStephen]

The rough outline is available. 

Also, please test Scott's IDE instructions.

I am beginning to think that we need an Intermediate Guide to the Joomla! API to follow the beginner's class which will be jbruni's material and the documentation the Dev Doc team has been assembling. It might be beyond the beginner level, once we started looking at the TON of material to go through first.

I am very interested in jbruni, Chris and Ian's thought on this, too. Especially in understanding where the Dev Doc Team hopes to see this material go. I have not seen many who have insight like jbruni in easily explaining the classes and we need to capture this before he figures out how much work he is doing!

OK - your ideas and viewpoints are welcome. I am also interested in someone taking over the wiki stuff for round 2, changing it exactly like they believe is needed. Volunteers?

Amy

[jbruni]

What do I think? Let me think...

I can´t express exactly in english (I´d like to use my primary language, portuguese, here...)

I kind of agree with Bruce (bascherz), I mean, he expressed some ideas that I am concerned (I have been thinking) about:

[quote=∓quot;bascherz"\]I don't know if it's absolutely necessary to know it in so much detail just to get started. I would actually consider that more of an advanced level of instruction. Explaining the entire API at that level of detail would take quite a long time, and I don't know if it really has as much value as a starting point as it will once developers get to the point that they really need to know what's going on inside the core.[/quote]

Actually, when I recently asked for feedback, I was with this kind of thoughts in my mind.

I have no answers.

As I said in another occasion, the writings I posted at 101 were only to SHARE what I was learning "by myself", and nothing else.
In fact, I am a "101", I wish to learn, but instead of asking I decided to make my first step giving something. Also, I learned and enjoyed very much writing that "sharing".

I wish I could do this job (this play!) with all the 164 framework classes!

Is it good? Is it weird? Where does it will lead?

Is it a good starting point? I think NO for the majority - maybe YES to a few. If I could maintain my effort and look at the whole Framework with this "insight eye", I could be writing the really desired material in the future, I could be really a "mentor" for begginers. The fact is I don´t have the knowledge nor the experience NOW.

Finally, I think there is a place for this work, I don´t know if 101 is the place, but I am open and flexible to listen and accept any good idea that come from J! people.

Shall I continue following this long and strange path?
Shall I rest and just wait?
Shall I change the focus?
I open this (and other) possibilities assuming there is an interest in the Dev Doc Team (or any other) in take advantage of my participation here.

Then I ask: what should I do?

(I was studying "tree.php" to complete the Base subpackage... Maybe I should JUMP / FOLLOW with "Observer Pattern" through Event subpackage and focus on PLUG IN features... Maybe what is needed is a change in "scope", I mean, do not analyze every single line of the core, but just summarize; study the interface and how to USE the class... I don´t know!)



You see... I focused only my own work, not being aware of the greater context. I am too new to Joomla! to be able to talk from a wider perspective. And I thank you for all helping thoughts and words! 

Did I answer you, Amy?

[bascherz]

Hey @jbruni, you should keep right on doing what you are doing if it is benefiting you and you continue to have the energy and enthusiasm to continue. I can tell you that others will also benefit from what you are doing. I think Amy has already reserved a place for this level of detail in her outline, and since the API doc wiki is lacking this level of detail it is definitely important to have it. But is it 101? Hmmm... I think it is much more advanced than 101. But I am confident that some beginners, perhaps others like yourself, will PREFER to start at that level. Personally, I would look to that level of information as reference material in the event I need to know more about what's going on "under the hood". It's great stuff, and very valuable as I said before.

So if you have the wish and the drive to continue and complete all 164, I say GO FOR IT!

[seadap]

jbruni,

I think the work you are doing is invaluable.  Please continue!  I also think you should study the classes YOU want and not go by any pre-determined pattern.  It's YOUR work, I'm just reaping the benifit of it. 

I also think that this information should be in the wiki - it's that important.

[AmyStephen]

We must make use of jbruni's guides to the class structures - and it must be placed into the wiki. Agreed 100%!

The only question in my mind is "where?" For maximum benefit, it should be inserted into the curriculum at a point that the learner is prepared to understand it and will begin to use it - or, at least understand when it will be used.

My biggest challenge at this point in the process is - I am a learner, too! So, it's very difficult for me to know where to place this material.

Question - why would a developer go to the framework and begin looking at classes and need to understand how to read that documentation, just like jbruni provided with JObject? Can someone come up with a scenario - a question a developer could ask - then, that might help us determine where this goes and how to ease it into the curriculum.

Look at the course "outline" and, for those of you who understand these concepts, ask yourself at what point would a newbie developer have sufficient knowledge to understand and make use of this material.

Also - it's clear that, if jbruni is willing to continue with the class/API documentation, the Dev Doc Team can plug him into already identified work that will benefit everyone. He is very good and there is an existing need!

Poor guy!  hehe!
Amy

[ianmac]

What do I think? Let me think...

I can´t express exactly in english (I´d like to use my primary language, portuguese, here...)

I kind of agree with Bruce (bascherz), I mean, he expressed some ideas that I am concerned (I have been thinking) about:

[quote=∓quot;bascherz"\]I don't know if it's absolutely necessary to know it in so much detail just to get started. I would actually consider that more of an advanced level of instruction. Explaining the entire API at that level of detail would take quite a long time, and I don't know if it really has as much value as a starting point as it will once developers get to the point that they really need to know what's going on inside the core.

Actually, when I recently asked for feedback, I was with this kind of thoughts in my mind.

I have no answers.

As I said in another occasion, the writings I posted at 101 were only to SHARE what I was learning "by myself", and nothing else.
In fact, I am a "101", I wish to learn, but instead of asking I decided to make my first step giving something. Also, I learned and enjoyed very much writing that "sharing".

I wish I could do this job (this play!) with all the 164 framework classes!

Is it good? Is it weird? Where does it will lead?

Is it a good starting point? I think NO for the majority - maybe YES to a few. If I could maintain my effort and look at the whole Framework with this "insight eye", I could be writing the really desired material in the future, I could be really a "mentor" for begginers. The fact is I don´t have the knowledge nor the experience NOW.

Finally, I think there is a place for this work, I don´t know if 101 is the place, but I am open and flexible to listen and accept any good idea that come from J! people.

Shall I continue following this long and strange path?
Shall I rest and just wait?
Shall I change the focus?
I open this (and other) possibilities assuming there is an interest in the Dev Doc Team (or any other) in take advantage of my participation here.

Then I ask: what should I do?

(I was studying "tree.php" to complete the Base subpackage... Maybe I should JUMP / FOLLOW with "Observer Pattern" through Event subpackage and focus on PLUG IN features... Maybe what is needed is a change in "scope", I mean, do not analyze every single line of the core, but just summarize; study the interface and how to USE the class... I don´t know!)



You see... I focused only my own work, not being aware of the greater context. I am too new to Joomla! to be able to talk from a wider perspective. And I thank you for all helping thoughts and words! 

Did I answer you, Amy?
[/quote]

I'll add some feedback here...

First off, I should say that the work that jbruni has been doing is fantastic.  It is very detailed and comprehensive.  Great work!

JObject isn't the place I normally would have started with, but as I read it the explanation given really helps to introduce some of the concepts that we find all over the framework.  It is a small picture look, but it helps in understanding the bigger picture.

I would certainly encourage you to explore whatever you want to explore and document as you go...  it is a great help and the resources will be beneficial to the community.

I think this level of detail is good for a few classes, but I don't know how helpful it would be for EVERY class...  I would think that once a person reads a few, they begin to understand the ideas and concepts of the framework, and would do better with more concise explanations.  i.e. once I know how to use power tool, you don't have to tell me how to plug it in every time and how to press the button...  This is my perspective, so if there are others, please speak up.

As I was explaining to Amy on the public chat, we are going in two main directions as a documentation team.  The first is the API reference.  The second is the API documentation.  The API reference is just that - it is a reference of every class, method and property in the Joomla! framework.  This is what you find in the references/joomla.framework section of the wiki.  So far, I think we have documented about 75 or so classes, maybe a few more than that.  The idea is to have examples with each method so one can look and see generally how it works and how you use it.  We have modeled this after php.net.  This doesn't have the level of detail that JBruni's explanation has, but the hope is that once you understand JBruni's type of explanation and are familiar with that, then these references will be enough to be able to understand what you're doing with it.

The API documentation is more documenting how to use the API.  This is more big picture stuff.  So, for example, how do you use the JParameter class?  What does it allow you to do?  What would you use it for?  One example that you'll see is the Creating Custom URLs page in the Tutorials/Framework link.  This documents the JRouter class and related ideas.  It isn't a detailed explanation of every method, but hopefully illustrates the concepts involved so that somebody can create a router.  These are more tutorial-style documentation.  They are not necessarily extension type specific - so they don't belong in the module tutorial for example, but are general framework ideas.  Some of these have to be made more visible because they get missed a lot.

I guess my recommendation would be to document a few more classes in this detail, and then get into describing how various packages and stuff are used.  i.e. the Parameter package has a certain structure - first, there is the JParameter class, which can store XML file data and INI file data.  The XML file data describes parameter sets.  This is laid out in the same format you find in extension XML files.  The INI file data specifies the values for the XML parameters.  The other classes you will find in the parameter package are the JElement class and its child classes.  The JElement class describes the interface for elements, and the child classes are the elements.  So, for each different type of parameter, there is a JElement class.  Describing this pattern in more detail would help a lot of people, I would guess.

Anyway, I say again that I write this from my own perspective (duh), and I say this to say that what I find useful might not be what others find useful.  We would be grateful for feedback as to what people are looking for in terms of documentation.  I hope others will speak up and share what they are interested in seeing.  Feedback can be a very helpful thing.

So, to conclude, I say, keep up the excellent work Jbruni!  If there is anything that we as the J!101 team can do to help support you or we as the documentation can do to help support you, speak up!  We are impressed by your work!  If you want a gig as part of the team, let me know!

If you can send me your details as well (i.e. full name, email address) then I will get you set up on the wiki.

Thanks,
Ian

[bascherz]

We're all in agreement then. By the way, the API documentation is fantastic. However, it is reference material. It is not where a beginner would start. Beginners like to start with topics at the "how to" level. For instance (in no certain order or hierarchy),

• How to decide what type of extension to write
• How to apply the MVC concept to your extension
• How to start writing a template, module, plug-in, or component
• How to write an installer for a template, module, plug-in, or component
• How to define administrator parameters
• How to access administrator parameters within an extension
• How to query the Joomla database
• How to debug and test your extension
• etc...(it's a pretty long list)

The text written for topics like the above will make HEAVY references to the API documentation. Eventually, as the junior developer becomes more knowledgeable about the framework, he/she will rely less on the tutorials and more on the API documentation (as Ian said). This is typically how someone who has written code before would want to start working within a new environment.

[seadap]

The only question in my mind is "where?" For maximum benefit, it should be inserted into the curriculum at a point that the learner is prepared to understand it and will begin to use it - or, at least understand when it will be used.

My biggest challenge at this point in the process is - I am a learner, too! So, it's very difficult for me to know where to place this material.

Question - why would a developer go to the framework and begin looking at classes and need to understand how to read that documentation, just like jbruni provided with JObject? Can someone come up with a scenario - a question a developer could ask - then, that might help us determine where this goes and how to ease it into the curriculum.

I'm not sure that it needs to be in the course work.  It almost seems more like reference material.  I believe that the curriculum should not be a complete hand-holding evolution.  At some point, developers must take the responsibilty to research their own questions.  I think if we provide the tools and examples of exactly how to do that, (pointing of course to jbruni's work) then that should be sufficient.

It's also been my experience that it's great to have a working ide for a component (even if it's the same one for everybody) from the start.  That way we can see all of the ideas and concepts come together.

Perhaps when we get the basics down (ie, ide setup, framework overview, mvc, research techniques, basic examples) then we can start phase 2 where we get a more in-depth look at the different classes etc.