12 replies to this topic

[sug15]

Essentially, it would be a "quick" documentation. You enter a keyword, function, etc. and the relevant function pops up, gives a one-sentence explanation, and gives an example. Just a little idea I had.

Would you find this useful? Is there anything that could make it more useful?

[kicken]

Enter it where?  And for what language? For PHP you can already do something like that by just going to http://php.net/function_name_here.  

[sug15]

Enter it where? And for what language? For PHP you can already do something like that by just going to http://php.net/function_name_here.

For PHP. The documentation could be better. Often I just want an example or a quick run through, and I don't want to have extra clutter. Probably more likely to be true for newcomers.

[.josh]

Maybe i'm missing something, but it sounds to me like you are just wanting to make a standard site search box?

[.josh]

Also, I disagree with your statement about how php doc can be better...how much experience do you have sorting through manuals? php is by miles one of the most well organized, clear, easily navigated documents out there, complete with useful examples and tons of useful comments in the entries, even before they implemented a rating system. It is second to none..

[Jessica]

Agreed, PHP's manual is one of the best there is. Compare it to something like jQuery. 

So I have to say, no, it would not be useful.

[Philip]

Agreed, PHP's manual is one of the best there is. Compare it to something like jQuery.

Ironic that you mention that; they recently updated their design, which IMO makes it easier to use. Still not the clearest, but it is a step in the right direction.

@OP - what you are suggesting sounds like what is built into most IDEs (syntax hinting). While useful, I wouldn't visit a 3rd party to do it. Integrate it into let's say, this forum, or other web app, sure. But a stand-alone site? Not useful IMO.

[sug15]

Ok, thanks guys. So essentially, it sounds like even though something could be made that was slightly easier to use, PHP's doc is still good enough that something like I propose would not be worth switching to.

Are there any other languages this might be useful for that don't have a great doc like PHP? Python maybe?

[.josh]

Perhaps you should better illustrate/explain what your idea is, because I still fall back to my original statement in that it sounds like a regular site-search input field to me? Virtually every online doc has a search box somewhere...you enter in a function name and it lists results. Usually the actual manual entry is the first result returned if the user spelled it right and all that... so I'm not really sure what more you're bringing to the table here...

[sug15]

Perhaps you should better illustrate/explain what your idea is, because I still fall back to my original statement in that it sounds like a regular site-search input field to me? Virtually every online doc has a search box somewhere...you enter in a function name and it lists results. Usually the actual manual entry is the first result returned if the user spelled it right and all that... so I'm not really sure what more you're bringing to the table here...

I made a quick mockup to give you a better idea. But, I think you've pretty much answered the question, unless I didn't explain it very well. It would work sort of like Google instant, the results would just be loaded via AJAX. "More details" would go to PHP's doc.

Edited by sug15, 30 January 2013 - 06:22 PM.

[.josh]

So it sounds/looks basically like what most IDE "auto-complete" features do. Not sayin' it's a bad idea, just saying it seems more like reinventing the wheel, not really seeing anything new or different from this. IOW between auto-completes from site search boxes or IDEs...this is kinda already covered...

Also, it's only really useful as a quick guide for people who already know what they are looking for but fail at remembering details like argument orders. If someone knows there is probably a function out there that does what they want but can't quite describe it, they are likely going to be entering into a search bar a description of what they are trying to do. That makes the rest of the search results returned more useful.


sidenote: I like auto-complete suggestion dropdowns for search boxes but fuck all i fucking HATE code auto-completers... I know a lot of people like it, especially since the "popups" do usually show syntax and descriptions etc.. but for me...it ends up hurting more than helping. Like for instance I use html-kit and I can't tell you how many times I've gone to make an opening php tag only to have html-kit decide I wanted an html p tag. /me shakes angry fist at auto-complete.

[sug15]

So it sounds/looks basically like what most IDE "auto-complete" features do. Not sayin' it's a bad idea, just saying it seems more like reinventing the wheel, not really seeing anything new or different from this. IOW between auto-completes from site search boxes or IDEs...this is kinda already covered...

Also, it's only really useful as a quick guide for people who already know what they are looking for but fail at remembering details like argument orders. If someone knows there is probably a function out there that does what they want but can't quite describe it, they are likely going to be entering into a search bar a description of what they are trying to do. That makes the rest of the search results returned more useful.


sidenote: I like auto-complete suggestion dropdowns for search boxes but fuck all i fucking HATE code auto-completers... I know a lot of people like it, especially since the "popups" do usually show syntax and descriptions etc.. but for me...it ends up hurting more than helping. Like for instance I use html-kit and I can't tell you how many times I've gone to make an opening php tag only to have html-kit decide I wanted an html p tag. /me shakes angry fist at auto-complete.

Haha, yes, I hate that too.

Are there any languages something like this might be particularly useful for? I get that it's sort of "meh, already kinda there" for most.

[Adam]

sidenote: I like auto-complete suggestion dropdowns for search boxes but fuck all i fucking HATE code auto-completers... I know a lot of people like it, especially since the "popups" do usually show syntax and descriptions etc.. but for me...it ends up hurting more than helping. Like for instance I use html-kit and I can't tell you how many times I've gone to make an opening php tag only to have html-kit decide I wanted an html p tag. /me shakes angry fist at auto-complete.

Amen!