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

Modify TOH titles and intro #34758

Open
wants to merge 3 commits into
base: master
from
Open

Modify TOH titles and intro #34758

wants to merge 3 commits into from

Conversation

@jbogarthyde
Copy link
Contributor

jbogarthyde commented Jan 13, 2020

PR Checklist

Please check if your PR fulfills the following requirements:

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
  • Documentation content changes
  • angular.io application / infrastructure changes
  • Other... Please describe:

What is the current behavior?

The headers in Tour of Heroes tutorial do not match the style guidelines, and use Angular-specific terms.
The introduction does not properly explain the status of TOH wrt the Get Started stackblitz tutorial.

Issue Number: N/A

What is the new behavior?

  • updates headers for sentence-style caps
  • updates page titles to be more descriptive (Routing -> Add page navigation, for example)
  • updates intro to better describe Get Started/TOH differences, intended audience

Does this PR introduce a breaking change?

  • Yes
  • No
@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 13, 2020

Copy link
Contributor

kapunahelewong left a comment

Just a few ideas. Thanks for requesting my review, Judy!


</div>
The **Tour of Heroes app** that you create with this tutorial is used the conceptual basis for many examples in this documentation set. Reading this introduction page provides sufficient context for working with those examples. You do not need to do this tutorial to understand those other examples. The Tour of Heroes tutorial is maintained here for context and continuity.

This comment has been minimized.

Copy link
@kapunahelewong

kapunahelewong Jan 13, 2020

Contributor

A few thoughts:

  • Remember to give sentences a new line each.
  • I don't know that the average reader or non-native English speaker will know the tech writer term "documentation set". I'd never heard it before working on the docs. I've suggested an alternative should you choose to edit it.
  • I deleted "maintained" so it would shift to the active voice with the intention of changing the wording, but then it read ok to me. Does it still convey your intention without "maintained"?
Suggested change
The **Tour of Heroes app** that you create with this tutorial is used the conceptual basis for many examples in this documentation set. Reading this introduction page provides sufficient context for working with those examples. You do not need to do this tutorial to understand those other examples. The Tour of Heroes tutorial is maintained here for context and continuity.
The **Tour of Heroes app** that you create with this tutorial serves as the conceptual basis for many examples throughout the Angular documentation. Reading this introduction page provides sufficient context for working with those examples. You do not need to do this tutorial to understand those other examples. The Tour of Heroes tutorial is here for context and continuity.

This comment has been minimized.

Copy link
@jbogarthyde

jbogarthyde Jan 13, 2020

Author Contributor

I think that last sentence was there because they were talking about completely replacing this with the StackBlitz one - but in light of recent discussions, that seems unlikely. StackBlitz doesn't introduce users to the actual dev process the way this type of tutorial does.
I'm getting rid of it altogether.

"tooltip": "Part 2: Build a master/detail page with a list of heroes."
},
{
"url": "tutorial/toh-pt3",
"title": "3. Master/Detail Components",
"title": "3. Create More Components",

This comment has been minimized.

Copy link
@kapunahelewong

kapunahelewong Jan 13, 2020

Contributor

The master/detail relationship is important as it shows the relationship between the components as being parent/child and that they show/hide as needed. I like the new active titles, but wonder if there's a way to keep the specific meaning while still updating to an active and engaged task as a title.

This comment has been minimized.

Copy link
@jbogarthyde

jbogarthyde Jan 13, 2020

Author Contributor

Using the term "feature component" - does that work?

This comment has been minimized.

Copy link
@kapunahelewong

kapunahelewong Jan 13, 2020

Contributor

hm, feature component is more general than master/detail but more specific than "create more...". Yes, I think "feature component" would work, but I'm up for other suggestions, too.

@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 13, 2020

Copy link
Contributor

aikidave left a comment

I've a lot of thoughts on how we need to better address the getting started experience with Angular. I've shared some of them in my review.

@@ -1,4 +1,4 @@
# Display a Heroes List
# Display a heroes list

This comment has been minimized.

Copy link
@aikidave

aikidave Jan 13, 2020

Contributor

Why not "Display a list of heroes?" It avoids the noun stacking of "Heroes List."

This comment has been minimized.

Copy link
@jbogarthyde

jbogarthyde Jan 13, 2020

Author Contributor

I thought of that, but thought it was kind of long. Trying the more general "Display a selection list"

This comment has been minimized.

Copy link
@kapunahelewong

kapunahelewong Jan 14, 2020

Contributor

What about "Display heroes"?

This comment has been minimized.

Copy link
@jbogarthyde

jbogarthyde Jan 14, 2020

Author Contributor

I'm trying to make the titles reflect the more general or abstract concept that the specific execution within the example is meant to illustrate. @aikidave, what do you think?

@@ -1,4 +1,4 @@
# The Application Shell
# The application shell

This comment has been minimized.

Copy link
@aikidave

aikidave Jan 13, 2020

Contributor

I think it's more important to put things in the context of the user's tasks. For example, this could be reworded as:

Creating a new project



If you're new to Angular, see the [**Getting Started tutorial.**](start)
The Getting Started tutorial covers the same major topics as this Tour of Heroes&mdash;components, template syntax, routing, services, and accessing data via HTTP&mdash;in a condensed format, following the most current best practices.
If you're new to Angular, you might want to try the [**Getting Started**](start) quick-start app first.

This comment has been minimized.

Copy link
@aikidave

aikidave Jan 13, 2020

Contributor

This paragraph (which has existed for some time) presents some problems. We have two tutorials, and we are basically telling people: "You don't need to do this tutorial, but if you don't at least read it, you won't understand all the other examples in our documentation."

I've created #34766 to address this further.

This comment has been minimized.

Copy link
@jbogarthyde

jbogarthyde Jan 14, 2020

Author Contributor

For the moment, I am trying to give someone who lands here an idea of how the two approaches are different, and what they can get out of either or both. Any more band-aid ideas? (...since it will be quite a while until the whole tutorial approach is sorted out and delivered, and new people are picking it up every day.)

@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 14, 2020

@jbogarthyde jbogarthyde force-pushed the jbogarthyde:jb-toh branch from ce02f98 to c0579bf Jan 14, 2020
@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 14, 2020

@jbogarthyde jbogarthyde force-pushed the jbogarthyde:jb-toh branch from c0579bf to f186b92 Jan 15, 2020
@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 15, 2020

@jbogarthyde jbogarthyde force-pushed the jbogarthyde:jb-toh branch from f186b92 to 32642a2 Jan 20, 2020
@jbogarthyde jbogarthyde requested a review from angular/framework-global-approvers-for-docs-only-changes as a code owner Jan 20, 2020
@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 20, 2020

@jbogarthyde jbogarthyde force-pushed the jbogarthyde:jb-toh branch from 32642a2 to e6c3296 Jan 21, 2020
@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 21, 2020

@jbogarthyde jbogarthyde force-pushed the jbogarthyde:jb-toh branch from e6c3296 to c658b43 Jan 22, 2020
@mary-poppins

This comment has been minimized.

Copy link

mary-poppins commented Jan 22, 2020

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
docs
In Progress
5 participants
You can’t perform that action at this time.