WIP: docs(tutorial): fix url inconsistency in tutorial chapters

[sreevani-ship-it]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Documentation content changes
[ ] angular.io application / infrastructure changes
[ ] Other... Please describe:

What is the current behavior?

URL to tutorial chapters do not match the chapter sequencing.
Issue Number: N/A
#17645

What is the new behavior?

tutorial chapter numbers and URL pointing to them are matching.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

[mary-poppins]

You can preview a9688e8 at https://pr24628-a9688e8.ngbuilds.io/.

[gkalpak]

You should also remove any file that is not used any more (e.g. tutorial/index.md).

IIRC, /tutorial is one of the urls that are eagerly cached by the service worker for offline access. This PR breaks that. Why not move tutorial/toh-pt0.md to tutorial/index.md (and redirect /tutorial/toh-pt0 to /tutorial)?

[gkalpak]

Unnecessary new line.

[jenniferfell]

Our first thought was to move toh-pt0.md into index.md, but that means we have to redo the example directory, which also affects stackblitz. So, we thought we'd first explore what happens if we have index.md redirect to toh-pt0.md.

My idea to prototype this was just to throw and http-equiv="refresh" content="0; url=http://example.com/" into the index.md, so we can see how everything feels if we make these changes (nav changes, filename changes, and content merge all have impact). @chembu knew more about how to do redirects for real in aio, so she tried playing with that. When/if we decide to go forward we'll clean up.

What are the implications of redirecting index.md? Doesn't /tutorial cause the browser to load /tutorial/index.html, so in theory if we change index.md (or remove it), then service workers will reload with the /tutorial bookmark? You advice greatly welcome.

[gkalpak]

Answer to #24628 (comment):

but that means we have to redo the example directory, which also affects stackblitz.

Not sure what this means. You could either rename a directory or add some name="directory-name" attributes to examples.

What are the implications of redirecting index.md? Doesn't /tutorial cause the browser to load /tutorial/index.html, so in theory if we change index.md (or remove it), then service workers will reload with the /tutorial bookmark?

Not exactly, but close. Everything will work indeed when online. But when offline, the service worker will only be able to serve the files that it has cached for offline usage. According to our current config, tutorial/index.md will get cached, but tutorial/toh-pt0.md won't.

We could fix this by tweaking our config (which needs to happen as part of this PR), but it much less straight forward than moving toh-pt0 to index 😁

[jenniferfell]

If we move toh-pt0 into index.md, can we keep toh-pt0 in the live example and download example file names?

https://angular.io/tutorial/toh-pt0#final-code-review
https://angular.io/generated/live-examples/toh-pt0/stackblitz.html
https://angular.io/generated/zips/toh-pt0/toh-pt0.zip

It would still make sense, because those files go with the first doc page which will be unnumbered or 0 in the nav. Is there any technical limitation or guideline/practice that requires us to rename those paths to

https://angular.io/generated/live-examples/index/stackblitz.html
https://angular.io/generated/zips/index/index.zip

[gkalpak]

You can keep the names, but you have to explicitly refer to them on the <live-example> tags. See https://angular.io/guide/docs-style-guide#live-example-from-another-guide.

[jenniferfell]

Simple fix migrated into PR #26099

[jenniferfell]

Tutorial parts 1-6: PR #26099 resolves problem for these parts. Resolution:

Tutorial
    Introduction
    The Application Shell
    1. The Hero Editor
    2. Displaying a List
    3. Master/Detail Components
    4. Services
    5. Routing
    6. HTTP

Introduction: Recommend leaving this page as-is, separate from the numbered parts. There are lots of 3rd-party links to this page, and redirection is complicated by this being the primary/index page for the group and available as angular.io/tutorial

The Application Shell: Three options:

1. Leave as-is ("The Application Shell" in nav without a number).
   It's a bit odd to have two intro sections without numbers--and this section is an actionable part, not just intro--but it's usable.

2. Change nav to "0. The Application Shell" to match its position and file names.
   It's a bit odd to have a "part 0", but it would help match the stackblitz, download example, and URL. It would also keep this section separate from both the intro (which is purely context and may be useful for those trying to understand mention of TOH from throughout the doc set) and part 1 where the user starts working with lists and data. It essentially parallels Getting Started in the context of the Tutorial.

3. Rewrite to merge The Application Shell and Displaying a List into one unified Part 1.
   This is more work, will require redirects of the old URL, and will require renaming of example files and links.

Recommendation is #2. Perhaps do as part of my next navigation updates.

Tutorial
    Introduction
    0. The Application Shell
    1. The Hero Editor
    2. Displaying a List
    3. Master/Detail Components
    4. Services
    5. Routing
    6. HTTP

@chembu @gkalpak Comments welcome.

[gkalpak]

Ideally, we wouldn't have part-0 (in URLs and guide names) to begin with. But since we have those, at this point I would prefer keeping the page title 1-base indexed and the guide names 0-based indexed (i.e. toh-pt0.md will have a title of 1. Do this and that).

That said, I can live with options #1 and #2 from above.

Another option:

• Change guide names to not use numbers at all (e.g. toh-pt0.md --> toh-app-shell.md). This breaks existing links to tutorial pages (which shouldn't be terrible, because why link to anywhere other than the start of the tutorial 😁) and makes it easier to insert/remove tutorial parts in the future.
  Not sure how @IgorMinar feels about breaking the links 😁

[jenniferfell]

Coming back to this: " the page title 1-base indexed and the guide names 0-based indexed " is exactly what users have complained about. They want the numbers to match.

That said:

• We're reducing investment in TOH and moving investment to a newer Getting Started/Tutorial replacement.

• The "right thing" for the current GS and TOH would be to rewrite both so that TOH doesn't repeat what the user did in GS in terms of installing CLI and creating the app shell. If GS were rewritten to create the TOH app shell, then the TOH can just pre-req doing the GS and start at Part 1. Ta da. Part 0 basically goes away. See new issue Simplify relationship between Getting Started and Tutorial (TOH) #27126

So I'm going with Option 1 for now: Do nothing. :-)

@chembu : Go ahead and close this PR. Thanks!

[sreevani-ship-it]

Fixed in a different PR.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}