Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Path to Raku (Docs) #3046

Open
JJ opened this issue Oct 4, 2019 · 2 comments
Labels

Comments

@JJ
Copy link
Contributor

@JJ JJ commented Oct 4, 2019

The problem

This issue has been created to discuss what needs to be done once, or when, the name has been changed to Raku, that is, once perl6/problem-solving#81 is accepted, perl6/problem-solving#89 is merged.

Suggestions

#2951 has been proposed, however it's in conflict now and I'm not sure that direct approach is the way to go. I propose the following roadmap.

  • As soon as we get the docs.raku-lang.org domains going, we create a "perl6" branch of the documentation.
  • Substitute Perl 6 for raku, perl6 for raku, and other related changes in the master branch of the documentation, that will be deployed to docs.raku.org
  • Changes in the perl6 branch:
    • Eliminate the possibility of editing, since those pages are not current any more.
    • Add a footer with a deprecation notice in the "perl6" branch, as well as an automatically generated link to the new, equivalent page. These pages will be deployed to docs.perl6.org.
  • The "master" branch will include a note, maybe in non-visible parts like the header, indicating that Raku was formely called Perl 6.
  1. Let's monitor a series of search strings like "perl 6 documentation" and "raku documentation" to see where they lead. Ideally, they should both return docs.raku-lang.org eventually.
  2. Change occurences of "Perl 5" to simply "Perl".
    1. Include file names here.
  3. The tooling will have to be changed to accommodate the new extensions as well as the old ones, as well as any change that's done to the name of the classes (there are lots of Perl6:: and Pod:: )
  4. Once tooling and documentation does not fail, is findable, then change the old docs.perl6.org pages to a 301 redirection to the new URL.

There are several reasons for taking this cautious approach:

  1. People will keep looking for Perl 6 for some time. We want them to be able to find the old documentation as well as the new one.
  2. We need the two sets of pages for the new ones to gather SEO juice. We need to be extremely cautious about this, since we don't want people to lose the old perl6 pages and not be able to find either the new ones.
  3. Changing the tooling will definitely take some time, and we have still not finished the transition to the new version.

Also, if there's a good time to overhaul the appearance of the pages, this is it. So we might as well make the new pages more dashing, add more pizzazz, or something like that. New branding with old pages is probably not a good idea.

(I don't know if this is more adequate for the problem-solving repo, since it involves also infrastructure; if that's the case, just move it there or tell me so and I'll do it)

@JJ JJ added the meta label Oct 4, 2019
@AlexDaniel AlexDaniel changed the title Path to Raku Path to Raku (Docs) Oct 4, 2019
@Altai-man

This comment has been minimized.

Copy link
Collaborator

@Altai-man Altai-man commented Oct 5, 2019

Substitute Perl 6 for raku, perl6 for raku

Perl 6 for Raku, perl6 for raku

?

Add a footer with a deprecation notice in the "perl6" branch

Footer is too hard to find for people, why not (not very annoying) a message at the top of the page? It'd be much more visible and makes a lot of people aware of the change, who do not communicate with community a lot, but use docs.

@JJ JJ added this to the Adaptation to Raku milestone Oct 14, 2019
JJ added a commit that referenced this issue Nov 3, 2019
JJ added a commit that referenced this issue Nov 3, 2019
Improves typography and phrasing. Refs #3046
@JJ

This comment has been minimized.

Copy link
Contributor Author

@JJ JJ commented Nov 3, 2019

For the time being, "deprecated" docs have been deployed to https://docs-stage.perl6.org

JJ added a commit that referenced this issue Nov 29, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.