Kudos to the documentation team

[T.J. Crowder]

The new docs Andrew pushed yesterday are a HUGE leap forward! Well
done to everyone who contributed to both the content and the improved
linkability and such. Major kudos!

-- T.J. :-)

[Clint Priest]

I would definitely second that, great work!

[Johan Arensman]

Wow! I didn't even realise they were updated until I read this message. Very nice work indeed!

--
You received this message because you are subscribed to the Google Groups "Prototype: Core" group.
To post to this group, send email to prototy...@googlegroups.com
To unsubscribe from this group, send email to prototype-cor...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/prototype-core?hl=en

To unsubscribe, reply using "remove me" as the subject.

[Mislav Marohnić]

On Mon, Apr 5, 2010 at 11:48, Johan Arensman <joha...@gmail.com> wrote:

Wow! I didn't even realise they were updated until I read this message. Very nice work indeed!

My coworkers still find old docs (http://prototypejs.org/api) by googling. I had to point them to new doc site. I think it's crucial to set up 301 redirects.

[Joost]

I have the same problem, because I like to use google to search for
stuff in the documentation but I end up on the old one. Also I think
the mouse wheel scrolling in the menu on http://api.prototypejs.org is
way too slow and should be fixed (it takes 10 seconds for me to scroll
down with the mouse wheel..).

Good work on the improved docs though.

[T.J. Crowder]

> My coworkers still find old docs (http://prototypejs.org/api) by googling. I
> had to point them to new doc site. I think it's crucial to set up 301
> redirects.

*ONLY* if all of the old information has now been ported over. Looking
at the documentation Lighthouse project[1], it looks like all of the
old "merge/update" tickets have been closed (yay!), which may mean
exactly that, someone from the docs team can presumably confirm that.

Once we're ready, 301s that live in those locations for a long, long
time are indeed appropriate. Or if 301s are hard in Mephisto,
replacing each of the API documentation articles with a link to the
new one.

[1] https://prototype.lighthouseapp.com/projects/42103-prototype-documentation/overview

-- T.J.

On Apr 5, 3:30 pm, Mislav Marohnić <mislav.maroh...@gmail.com> wrote:

[Tobie Langel]

A practical solution would be a well designed 404.

We could get pdoc to generate it with a search field, etc.

We could also try JS redirection.

Anyone wants to give it a shot?

Best,

Tobie

On Apr 6, 8:42 am, "T.J. Crowder" <t...@crowdersoftware.com> wrote:
> > My coworkers still find old docs (http://prototypejs.org/api) by googling. I
> > had to point them to new doc site. I think it's crucial to set up 301
> > redirects.
>
> *ONLY* if all of the old information has now been ported over. Looking
> at the documentation Lighthouse project[1], it looks like all of the
> old "merge/update" tickets have been closed (yay!), which may mean
> exactly that, someone from the docs team can presumably confirm that.
>
> Once we're ready, 301s that live in those locations for a long, long
> time are indeed appropriate. Or if 301s are hard in Mephisto,
> replacing each of the API documentation articles with a link to the
> new one.
>

> [1]https://prototype.lighthouseapp.com/projects/42103-prototype-document...

[Mislav Marohnić]

On Tue, Apr 6, 2010 at 11:00, Tobie Langel <tobie....@gmail.com> wrote:

We could also try JS redirection.

It would partially solve the problem, but old pages would still remain in Google index for too long a time. We should get access to the server level and set up rewrite rules or similar. 

[Robert Kieffer]

I disagree.  404'ing the old docs is not the correct action.  404 means "not found", but the user is requesting a page that he (and you) know exists... it's just not at that location any more.  Thus, a redirect is the way to go.  I'd suggest the following

- Move the old docs somewhere they're still available, but under a different URL.

- 301 (or 302) redirect old URLs to the new documentation as appropriate

- In the new documentation, provide a "old API docs" link to wherever you moved the old docs to, so people can still get to them if they need to.

- Set up robots.txt file to tell search engines to ignore the old docs

- rwk

[joe t.]

+1 for the scrolling. The navigation between documentation links has
much improved, but the navigation panel still has issues. The wheel-
scroll is painfully slow. Even clicking in the scroll bar doesn't work
as expected. When you click a position in the scroll bar, usually it
jumps to where you clicked.

Otherwise, the documentation itself is phenomenal, and thanks to all!
-joe t.

[Mislav Marohnić]

The scroll bar is native to the browser, meaning it's the same as in a regular window, iframe or frameset. The navigation panel should scroll with same methods and speed as every window in your browser.

[Tobie Langel]

Robert, that would be great. We unfortunately don't have this level of
access to the server.

[Robert Kieffer]

Urm... really?  You can do 404's but not 301's?

Not saying I don't believe you, I'm just surprised that a project as mature as prototype is hosted in an environment that doesn't support basic .htaccess-style configuration.

On Tue, Apr 6, 2010 at 6:12 AM, Tobie Langel <tobie....@gmail.com> wrote:

Robert, that would be great. We unfortunately don't have this level of
access to the server.

--

[Tobie Langel]

> Urm... really?  You can do 404's but not 301's?

I was suggesting crating a good 404 page. Not modifying the http
response code.

> Not saying I don't believe you, I'm just surprised that a project as mature
> as prototype is hosted in an environment that doesn't support basic
> .htaccess-style configuration.

There's historical reasons to this. We're in the process of migrating,
though (not that this will change much in terms of low-level access).

Best,

Tobie

[Clint Priest]

If you're on a PC you can adjust your wheel-scroll settings in Control
Panel -> Mouse -> Wheel. I think the default is 3 and I usually
adjust mine up as well.

[toxcct]

A HTTP 301 seems a better solution as it stands for "Permanently redirected" to a given URL...

the header should look like :

HTTP/1.1 301 Moved Permanently

Location: http://www.newurl.com/

2010/4/6 Tobie Langel <tobie....@gmail.com>

[toxcct]

BTW, if the ".htaccess" file is not accessible or cannot be updated, it is still possible to redirect from the server-side language used (header() for instance with php)...

2010/4/6 Robert Kieffer <bro...@gmail.com>

[T.J. Crowder]

Tobie,

Can we use JavaScript on Mephisto pages?

-- T.J.

[joe t.]

Agreed, and it appears to be specific to Firefox. However, i can't
recall any other circumstances (iframe, CSS overflow, etc) where the
scroll bar behaves differently. The new API page is the only time i've
seen this behavior. Peculiar.

Oh well, it's hardly the end of the world. :)
-joe t.

On Apr 6, 8:31 am, Mislav Marohnić <mislav.maroh...@gmail.com> wrote:
> The scroll bar is native to the browser, meaning it's the same as in a
> regular window, iframe or frameset. The navigation panel should scroll with

[Tobie Langel]

> Can we use JavaScript on Mephisto pages?
>
> -- T.J.

Yes, but we're moving away from it.

[T.J. Crowder]

> Yes, but we're moving away from it.

So a JavaScript solution would work now, and later (since I assume
you're moving from Mephisto to something else that *also* supports
JavaScript). If 301s work later, great, but if not there's a fallback
position.

A script included on each old API page that reads the current location
and figures out the new URL and inserts a prominent "This info is old,
go look here instead" box at the top (worded perhaps *slightly* more
carefully) sounds like a half-day project to do right. (It sounds like
an hour-long project, but you know it gets more complex and you get
into ito.) I have a half-day I can give it at the end of the month,
but not sooner, if that would be useful.

-- T.J.

[Tobie Langel]

You're help would be really welcomed, TJ.

We're moving to github pages as it makes contributing to the website
the same process as contributing code or documentation.

I've started the project already: porting the whole blog archives to
jekyllrb and disqus comments (preserving all past comments in the
process).

Your help is as usual, most welcomed, especially since I'm hoping to
merge parts/whole of your unofficial wiki content into it in the long
run (and if it's ok with you, of course).

Best,

Tobie

[Tobie Langel]

Oh, the repo is here: http://github.com/sstephenson/prototype/tree/gh-pages

[Mislav Marohnić]

How about we create a prototypejs GitHub user and have the site at: prototypejs.github.com?

[T.J. Crowder]

Hi,

> Your help is as usual, most welcomed, especially since I'm hoping to
> merge parts/whole of your unofficial wiki content into it in the long
> run (and if it's ok with you, of course).

It's funny you should mention that. I'm under the gun for the next few
days, but one of the tasks on my "to do" list for later this month is
to ping the user list to see if anyone actually wants the wiki, since
I noticed a few weeks back that in the last *year*, there had been
precisely one update to the wiki by someone other than me. :-) (Doug
Reeder added an on0 handler to the bulletproof ajax page.)

Enh, it's not going to take long, I'll go do that now.

-- T.J.

[Tobie Langel]

> How about we create a prototypejs GitHub user and have the site at:
> prototypejs.github.com?

We'll be using prototypejs.org directly. It's supported by Github.

[Tobie Langel]

> Enh, it's not going to take long, I'll go do that now.

Awesome.

I don't know if you're familiar with jekyll[1], but his sports built-
in templating and markdown/textile parsers.

Best,

Tobie

[1] http://jekyllrb.com/

[Mislav Marohnić]

On Thu, Apr 8, 2010 at 15:11, Tobie Langel <tobie....@gmail.com> wrote:

We'll be using prototypejs.org directly. It's supported by Github.

I see. In that case, you have to ensure that old URLs are preserved. Once you're on GitHub, there will never be a chance to do 301 redirects.

If you need help porting content, contact me. I've written an HTML to Markdown parser: http://github.com/mislav/remark

I've used it to port my own blog to Jekyll once I've lost the original markdown sources.

[T.J. Crowder]

> ...I've written an HTML to
> Markdown parser:http://github.com/mislav/remark

Oooooh, I just know that could be very handy indeed...

-- T.J. :-)

On Apr 8, 2:51 pm, Mislav Marohnić <mislav.maroh...@gmail.com> wrote:

[Tobie Langel]

> I see. In that case, you have to ensure that old URLs are preserved. Once
> you're on GitHub, there will never be a chance to do 301 redirects.

Are you suggesting we move the new documentation elsewhere
(prototypejs.org/doc) for example and keep the old, 1.5 doc structure
on prototypejs.org/api but replace the content with a link to the new
documentation or maybe an HTML refresh?

Isn't that just a glorified 404?

[Mislav Marohnić]

No, you got me wrong. I wasn't talking about the docs, I meant generally current pages on the site like blog posts, "/core" page and so on. When I was moving my dynamic site to (static) GitHub I double-checked to ensure that I didn't change any URLs.

As for documentation, I would replace existing pages on "pjs.org/api" with new docs if it was possible, but alas it isn't. The URLs are generated different: "/api/hash/clone" vs "/doc/language/hash/prototype/clone/". So I'm all for keeping the new docs where you started putting them ("/doc") and doing something with JavaScript on old docs page ("/api").