Documentation: not just new, but also improved
When we officially released 1.6.1 last week, we also published new documentation, the first official docs generated with PDoc.
Tobie, ear to the ground, brought to my attention what many of you were saying (on the blog and on Twitter): the new docs were harder to navigate and, therefore, harder to browse. Though I had eventual plans to re-do the navigation, the instant feedback showed it was a more critical issue than I’d guessed. So I spent the last week making some changes to the template we use to generate the docs.
You can see the results at api.prototypejs.org. The biggest change is obvious: a fixed, always-visible sidebar that makes it easier to move from section to section. Typing in the search box replaces the hierarchical navigation with a list of matching results. Clearing the search box (use the ESC key as a shortcut) switches back to the ordinary navigation. The sidebar will preserve state from page to page — it’ll remember your search term and the scrollbar position.
The docs aren’t perfect yet, but they’re good enough to use. I’ve tested them on Firefox 3.5, Safari 4.0, and IE 7–8. If there are glitches in these browsers or others, please open issues on the GitHub project. (If you, as a JavaScript developer, are still using IE 6; I’d like to take you out for a beer and ask you why.)
We intend for this to be default template included with PDoc, albeit without the Prototype branding. And now that we’ve accomplished the most pressing goal — getting PDoc to generate comprehensive and canonical docs for Prototype — we can focus on the big ideas we’ve got for the next version of our inline documentation tool.
Sorry, comments are closed for this article.
Comments
Awesome! The new doc looks really slick.
Great job on the doc section ! I use this one very often and I really appreciate your work :)
The searchable list in new documentation is nice. But to be honest, I really miss all the details and examples from the old documentation. Just compare these:
http://api.prototypejs.org/language/string.html#toqueryparams-instance_method
http://prototypejs.org/api/string/toQueryParams
The examples made me learn a lot, they helped me to understand lots of things. Do you plan to add them to the new documentation system? I hope so.
Very good work ! The new version is really better than the “first new version”.
I suggest you to indent a little the h1, h2 and ul to make the doc even easier to read. You could also remove the blank on top of each page to have more content displayed when changing pages. If you want me to send a modified version of the CSS like I imagine it, I’ll be glad to help you.
Excellent, very nice improvement—thank you for investing time in Prototype and the website/documentation/marketing of it.
@Riki: Yes, we will restore all the examples as soon as we can. Porting those docs over is a manual process.
Hey!
Great job on the new documentation pages.
One thing you might want to add in the ‘Using Prototype’ section, inform the user that google hosts the prototype lib at http://code.google.com/apis/ajaxlibs/documentation/index.html#prototype
Great work!!
Nice one Andrew!
Love it :D Good work Andrew and co
Really good stuff…thanks for responding so fast to people’s requests!
Well, I’m glad you listened to us and made the change.
One thing that I think would benefit all of us, is to make it Community Oriented.
Let us contribute examples, tricks and tips in a comment system for everybody to see. More people will learn and further. Take for example the PHP online doc, everyone contribute to the docs and give their examples.
IMHO, that would benefit all of us and the new prototype prospect.
PT 4 Life!
Personally I like the style of the old documentation better. But I guess thats a matter of taste. However what I do miss now is all the code examples. Wouldnt it be a good idee to keep the old documentation along with the new pdocs until all the new docs have been completely updated ? For my daily work this would be very helpful.. Thanks for the new release though !
I’m happy to hear that the examples will be coming back. One thing I do miss though is having the the methods listed in the navigation.
Sorry, but I really really don’t like this new API docs. I cannot find anything as easily (or at all) like I used to.
Maybe you can reduce height of header and footer on documentation pages – they take too much place.
It would be nice to be able to actually try out some of these examples on the website. But since all the documentation pages seem to reference “version 1.5.2_pre0”, its not really possible.
In other words, let’s bring this site into 2009?
Joshua, why don’t you have a look at the new documentation before complaining?
You’ll see it’s referencing version 1.6.1.
I understand that from time to time things and people need to change; and, that change is often a good thing. But, in this case (at least based on the docs up as of today), the old style was definitely much better. The mere fact that so many people have written about their dislike of the new docs rather than the new features/improvements added to the framework, speaks volumes in my opinion.
Hi there, well, I must agree with all here: Miss examples, as I used the api docs as a quick reference card.
Anyway, thanks for all your work.
New, maybe, but not improved. Incomplete for one thing, and harder to navigate for another. Please leave the old docs online until the new docs are complete!
I like the new document updates. I don’t know why you guys are getting as much flak as you are, it’s categorized so much better!
My only request would be to make the documentation text a fluid width instead of fixed. I’ve got a large monitor (22”) so I’ve got all this extra space (and scrolling :P) that could be eliminated if the text width was proportional. Just a minor thought.
I liked the old one but this is better. Don’t listen to the whiners haha.
@Mardix: We’re always happy to have contributors over at the unofficial wiki: http://proto-scripty.wikidot.com/
Now, I can’t find the used function example what I see in the old api documentation. I lost my time
Yeah guys. PT is awesome, but now the doc is not helpful at all with this new version. People don’t even talk about the new features and stuff available.
The old API used to be a reference point. It was successful because of the way it was presented and organized, with examples etc.
Now the new layout is just WTF! to everyone who used the old api docs.
The problem is here guys, PDOC is great but it’s not working for PT. And this is hurting us (developers), future developers, and the existence of PT against the web darling JQ.
I love PT better than JQ, the doc was a main keeper. Some people may be sharing the same feeling as myself, and may sadly leave PT to JQ, since everyone seems to embrace it.
As a developer it’s good to follow the crowd. PT is in the right way, but the trade off is greater now. And this api docs is not helping but downgrading the PT to something else.
Please make a good site and good api for PT site.
PLLLLZZZZZZ
Hi, the format of the new docs are nice and slick-looking, but PLEASE include the examples from the old version. In fact, please include MORE examples of usage. I’m still just referring to the old API docs.
I love the fact that you’re advancing your API docs but … I hate to say that it’s really hard for me to navigate through while the other one was fairly easy for me, though it seems like its just different (not worse) so I’ll get over it. Plus the all-white look is just blah to me. Make the sidebar on the left have some background color again and you GET that 50px top margin off of the masthead div! C’mon now! :)