New Documentation suggestion

Published by: jack 2009-01-07

Hi,

I have a quick suggestion for the API documentation that could make it really nice to use. It could have a comments section very much like php.net has. I have learned more things about php inside those comments (best practices, security concerns, tips and tricks) than I have ever learned from reading books or doing tutorials on php.

By having this, it could also help with the request for more examples and more information because it is always easier to post a comment with a quick example than it is to write out a tutorial on a wiki. This way if I want to figure out how to use JsonStore I could just go to the JsonStore section in the API and I could hopefully answer all of my questions right there on one easy to find page.

This is the only thing I have found I wish you guys had to make Ext easier to use. Other than that you guys have built a great library and have awesome forum support for it. Thanks for all the work you guys do to make our lives easier.

please don't take a holier than thou approach I don't know what part of my response gives you that impression. Nobody said it wasn't a useful feature, I'm just pointing out the issues with the suggested approach, in the Ext world.

If the idea of users contributing to the documentation works so well, why is the amount of documentation in the wiki not increasing? Anybody can post examples or further explanation, but I can count on 1 hand the number of the threads where somebody recently said 'Hey I just updated the wiki about this topic'.

The docs are autogenerated out of the source at the time of a release. I would think it would be difficult to maintain links to a wiki or other comment repository and make them viewable. The currently is a wiki setup (http://extjs.com/learn/Ext_Manual) with separate sections for major components which could be broken down further. I don't see it getting much use or new material, so I'm sure how much better things would be if directly linked to the doc. Additionally, the API doc is official manual of the software. Opening it up to comments from the community would require moderation on the part of Ext, more so than the wiki - not sure that would be an effective use of resources at this point.

One pitfall is that the comments would need moderating by someone with deep Ext knowledge.

Otherwise when a novice stumbles upon a solution, they may post some non-optimal example code which may then be followed. If you look in the Wiki, there are a few examples of bad practice.

You'd end up with "cargo cult" solutions proliferating.

http://en.wikipedia.org/wiki/Cargo_cult_programming

I see this when people post their code. I can see unchanged portions of code from examples/ included with no learning having taken place.

You're right - I apologize for my tone, I should have been more concilliatory.

And you're right about the wiki. No one contributes to it. But just because it doesn't work as a form of user contributed documentation doesn't mean nothing can.

I think the success of the commenting feature of PHP's manual shows us plain and simple that user contributed documentation is great and well appreciated by the community - now you have to ask yourself why Ext's user contributed documentation is not so great.

One major difference that comes to mind is that Ext has provided a wiki which is disconnected from the main documentation, while PHP has provided in line commenting. Users are (like it or not) lazy, and are ultimately more likely to find and post information if that can be done in the same place as the documentation.

Honestly, I'm not doing this just to stir the pot or be a pain. This is NOT a complaint - I am very appreciative of the support offered on these forums. Ext is a great project, and I'd love to be able to help out however I can. It's that spirit that causes me to suggest things like this - and that same spirit that would have me posting useful bits of information in the comments all the time.

You might say, "then why don't you post in the wiki?" But to be honest, I don't post in the wiki because it doesn't seem like anyone uses the wiki. Why spend valuable time on a resource that doesn't seem to be used? It may seem like a chicken-and-the-egg problem to you, but ask yourself: would the same problem exist for an API doc commenting solution? It wouldn't, because likely contributors KNOW that people use the API docs, so of COURSE their comment would be visible and thus worth their while.

@tyran - not sure about your assessment that it would require more resources from the ext team.

The issue is that it would require a new system of some sort. There's no magical "enable comments" switch that we can flip. It could obviously be done, but it would take a fair amount of effort that we don't really have time for at this time. The fact that our docs are generated to text files (as Tim mentioned) would further complicate it as well. It would not be nearly as easy as you might think.

This a very nice idea indeed. Right now I am struggling to understand the breadth and depth of Ext. I am going through the FeedViewer3 example line by line to understand what's exactly been done here. The wiki documentation was a disappointment as I saw only few soft links created here and there. I guess, many are not having a good idea on how to start contributing to wiki. I have some silly doubts which I am ashamed of asking because I know I can make it if I spend enough time on it. Time is the real constraint. My request to Ext team is to open up existing documentation as a base for the users to further contribute (I don't know about license issues)

Thanks

I think you can stop arguing the benefits of PHP-style comments. No one yet has disputed that. ;)

I love the idea. The comments section on php.net is probably one of the most valuable resources php has.

It would be great if extjs had something like this too.

I think this would be something very valuable aswell. Good suggestion!

As a new user trying to find my way around Ext I can only agree that more code examples are needed in some fashion whatever that may be, and if that can be done by the community then all the better.

Before the support team jump on me saying there are *loads of examples*, then perhaps I'm trying to do something unusual as none of them are of much use to me.

However that may be because I am not a Javascript expert so I have to learn whats going on and how to do stuff purely from examples, play with them and work out how to get what I want done. When you're switching between using php, perl, asp.net, c#, vb.net plus custom languages (dont ask) in the course of the same week then the simplest of examples can save you hours of messing about.

The API docs themselves really dont help me at all, as I've no idea what theyre on about most of the time. This is nothing against Ext, I have the same problem with any language API documentation (even PHP) that doesnt provide code examples of usage. Perhaps its just the way my brain works ... :((

I've learnt a lot in the last week on building trees from JSON via PHP from my Mysql database, grids from both XML and JSON/PHP/MySQL. Having spent a lot of time myself writing documentation for other peoples products I do know what a pain and hard job it is, believe me, and will contribute what I can, when I can, to the Wiki or wherever. Providing that is I can find out how to do what I want ....

Anyway, great product and as there's a lot of traffic on the forums too, thats a good sign too. Keep it up and Happy New Year to all

We just went through this same discussion a month or two ago. Yes, we all know that more examples would be good. If you search for the previous discussion, my reply was that as we have time we'll continue to add more. There are a lot more now than there were for 1.1. This has to be balanced with many other things (writing code, providing support -- in forum and offline, writing API docs, running a business....). It takes a lot of time and effort to produce examples, and it's an ongoing process.

What about creating a section in the forum for posting snippets of code? Then give moderators the ability to link single posts as comments to individual methods of the documentation.

And maybe automatically link posts that are rated 5 stars.

Actually I do think tim argued that since the wiki is not being used, user contributed documentation has not as yet proven itself useful. I was simply using PHP to argue that, in fact, it has.

Your point about the effort required is well taken. I have no idea what you guys are using to generate docs, and I realize it may be third party software. I guess I assumed that because the docs are so Ext-ized, it was probably a home spun effort.

But even so - would it not be possible to modify the HTML template to include a snippet of PHP (or your language of choice) code to list out the comments? I've implemented commenting systems before - generally you just need two database tables (in this case, one to hold a row for each doc page - which could be dynamically generated as comments are posted, just store the originating URL or something unique - and one to hold a row for each comment and a reference back to the parent table).

Perhaps I am being naive. Any interest in sending me a copy of whatever you're using to generate the docs and seeing if I can come up with anything on my own?

Or how about integrating a wiki-style of comments section into the api documentation? Seems like it could be very nice.

I second the idea for allowing comments for each function, this would be a GREAT resource. I have spent a lot of time browsing the forums for a simple examples on how to use certain methods. I think in the long run, the trouble to implement such a feature would be well worth the effort (saving everyone time).

Plus, I don't think that the documentation being generated from a text file would complicate it that much. You would just need a separate table that links methods to their comments.

For example, the clicking on the Ext.DateField.setValue(...) in the documentation could make a request to a page like extjsdoccomments.php?item=Ext.DateField.setValue ... this way regenerating the documentation wouldn't cause too many problems.

Just my 2 cents.

I love the idea. The comments section on php.net is probably one of the most valuable resources php has.

It would be great if extjs had something like this too.

yeah... the language sucks, but their comments system is great! ;)

The issue is that it would require a new system of some sort. There's no magical "enable comments" switch that we can flip.

What about the comments icon that jack had on his blog back in the 'ol days?

Just insert these little babies http://www.jackslocum.com/blog/images/cmark2.gif and run it off a json loader from ext.com? mimimal code change...

Refer Jacks Blog:
http://www.jackslocum.com/blog/2007/04/03/ext-js-launches/

@tyran - not sure about your assessment that it would require more resources from the ext team. actually I think it would require less effort. you are already moderating the forums, and forum traffic has the potential to be greatly decreased if a commenting system were put in place. so, you would spend less time overall because you would have less inane forum posts to respond to since answers would be readily available in the api docs themselves.

forums are hard to search - information is difficult to find - so people post dupes and increase the overhead for you. comments on documentation are right there, impossible to miss.

besides, would it have to be a public comment system? what if you gave select members of the community access after they had submitted some number of useful and intelligent comments? lots of open source projects use this approach to govern access to their source code repositories.

please don't take a holier than thou approach - recognize that this is an INCREDIBLY useful feature of PHP's documentation, and perhaps open your mind to learning something from one of the most successful open source projects out there.

I'm not trying to be a jerk, just trying to make a point.

Brian, maybe its me but I thought the main point being said here is that more examples from the community should mean less work required from Ext so you can get on with what you are supposed to be doing.

That was what I thought I was saying anyway.

You'd end up with "cargo cult" solutions proliferating.That's funny! My curmudgeonly side would consider the whole of PHP to be such ...

On a more serious note, I would/will contribute to the wiki (and likely get corrected on some things),
but I am presently up to my ass in alligators.

My hope is that my work will lead to a large license order for Ext.
But in any case, I'm spreading the good word as widely as I can.

--dan
(who, like everyone else would appreciate more examples,
but understands the law of diminishing returns)

Lack of contribution to the wiki is one reason for not trying to build a comment a system into the doc. People begged and pleaded for a wiki - it was added, but it's not being contributed to very much. Contrary to the previous poster's opinion that it would not complicate things, it would indeed be a large effort.