I've noticed today, while adding some instruction annotations to the graphql-js tutorial, that one of the places I was trying to add it to wasn't working. It seems to be something related to ordered lists. I'm adding <Instruction> right before such a list like this:

It's time to start creating your project. For this, follow these steps:

<Instruction>

1. First, you'll need is to have Node.js installed on your machine. If you don't yet, make sure to do it [now](https://nodejs.org/en/). Note that the code samples here assume the latest versions of Node.js, with ES6 support, so it's best if that's what you have as well.
2. Setup your **package.json** by typing `npm init -y` in the terminal, inside the folder of your choice.
3. Install dependencies: 

```
npm i —save express body-parser graphql-server-express graphql-tools graphql
```

</Instruction>

But it's just ignored when I run the site with gatsby:

If I move the opening <Instruction> tag up to the paragraph right before the list, it's detected, but the list itself isn't shown:

I've just noticed that links inside instruction blocks are not very noticeable. They look like regular text unless tou actually try hovering over them, which can be bad in some cases, as the reader needs to know about the link beforehand.

For example, without hovering:

After hovering:

I'd expect the links to show up as bold text or another color, like they do outside instruction blocks, for example:

Just a suggestion :)

Currently the mutations look like the following:

type Mutation {
  signinUser(email: AUTH_PROVIDER_EMAIL): SigninPayload!
  createUser(name: String!, authProvider: AuthProviderSignupData!): User
  createLink(description: String!, url: String!, postedById: ID): Link
  createVote(linkId: ID, userId: ID): Vote
}

One problem is how are we going to handle validation errors.

For example createLink can fail if url is already posted or description is too short.

The current schema doesn't express this. If keep the current schema, the only way to handle is through the graphql build-in errors, which are quite hard to handle on the client forms.

In my projects, I use the following format for mutations:

type Mutation {
  // have Relay style input, makes it easy 
  // to get form state and dump it directly into the mutation
  // (this would also make the schema usable in Relay examples)
  createLink(input: CreateLinkInput): CreateLinkPayload
}

input CreateLinkInput {
  description: String!
  url: String!
  postedById: ID
}

// all mutations return `node` (created/updated/remove) root node
// and array of errors  (having those make it easy to present them in a form)
type CreateLinkPayload {
  node: Link
  errors: [ValidationError!]
}

// error contain field, message (can be code or user presentable string)
type ValidationError {
  field: String!
  message: String!
}

What do you think?

We need to agree to the terminology for the following things:

• "Chapter": A piece of content as part of a "Tutorial" (usually a page of content with a distinct URL and backed by a single Markdown file. Often also contains a video)
• "Tutorial": A collection of chapters to teach a specific technology (Examples: GraphQL basics, React + Apollo, React + Relay...)
• "HTG": Acronym which can be used at least for internal documentation.

Challenges

• Mobile/responsive design
• How to display content of previous track?

Draft

I get it really doesn't matter but shouldn't

7-.using-data-loaders.md

be named

7-using-data-loaders.md

Challenges

• How to highlight a certain track as the default choice?
• How to separate between backend and frontend tracks?
• Plan for more content tracks
• Make clear that advanced GraphQL lessons are not mandatory to continue with FE/BE tracks
• Mobile/Responsiveness

Draft

In the next chapter introduction, fleible needs to be flexible.

• First create the example project in go (a Hackernews clone based on the GraphQL schema that’s also used in the other frontend/backend tracks)

• Then write the tutorial similar to the other tutorials

Todo General

• content overview landingpage (1h)
• author bio view, author bio data, author frontmatter (1h)
• video author view (0.5h)
• final success screen (2h)
• add bonus chapter screen (0.5h)
• localstorage tracking + score calculation (1h)
• reflect seen chapters to steps (0.5h)
• implement question data structure + handling of wrong questions (0.5h)
  • hide question when answered correctly
  • show correct next chapter count n
  • also reset answers
• minor sidebar css issues (in sum 1h)
  • bullets background color (10min)
  • last point without line (15min)
  • GRAPHQL THEORY same alignment as points (5min)
• nav dropdowns (1.5h)
• search (1.5h)
  SUM: 11h

added later

• fix [object Object] problem in prerendered versino
• implement stack switch
• increase animation time based on path length
• stop answers from jumping
• hide skip when answered
• vertical alignment questions
• menu dropdown - real links
• menu dropdown - close on click
• search - real results
• explore caption for image solutions
• video play icon
• remove header easter eggs

Mobile

Todo Mobile

• landingpage (4h)
• markdown (1h)
• questions (0.5h)

Needed Design Solutions Julian

• done chapter in Chooser on Landinpage
• Chapter overview - overflow, same for sidebar
• success screen mobile

Needed SVGs

• logos for different technologies
• header hamburger svg
• next chapter + bonus icons
• play symbol video preview
• medal for success screen

Mobile Responsiveness Julian

• Intro
• Chooser
• Header (just nav), Tim will do dropdown later
• Learn by Building Section
• Community Section
• Content Overview Section

Questions

• Watch Overview: Video modal?

Fine Tuning

• Relay Logo too big
• more lineheight for content overview
• line height of copy

Feedback @schickling

• Track selection: Backend tracks should include the language logo (nodejs + graphql logo, python + graphene logo, ...)
• Fav icon is missing
• Remove Lee Byron + Facebook for now
• Add Sashko + Apollo logo
• Hover states
• Adjust headline sizes to match Graphcool docs
• Reflect site title in <title>
• Use same logo order as in design for tutorial selection (react/apollo in the center)
• Add beginner's choice
• Success section should have coloured confetti 🎉
• Test section: The skip button should be hidden when answered correctly
• Frontpage: Video icon + duration should be clickable and directly trigger autoplay on the chapter page
• Replace hackernews picture with video (use ffmpeg to compress - see graphql-up/freecom for example)
• Content folder needs to be on root level: /content
• Make Graphcool link in footer a subtle link
• Add rounded arrow to playground section on frontpage
• Make community section rather wide than high
• Top nav github button should be target=_blank
• "Edit this page on Github" button
• Add preview banner
• Remove docs label on frontpage playground
• Page flickers on first load
• Content doesn't scroll smoothly on mobile
• frontpage playground: Query is malformated

Feedback @nikolasburk

• Add "Coming Soon"-label in chooser

"idendity" should be "identity"

• CLI import feature
• Include relational meta info in subscription: https://github.com/graphcool/api-bugs/issues/96
  - [ ] Authentication based on project.graphcool / authenticable types
• CLI enable email auth provider

Optional

• Relation constraints (at most 1 vote)

Ideas:

• Based on GraphQL logo
• Should communicate "learning" or "tutorial" 🎓
• Possibly GraphQL pink

image with url https://iimgur.com/zvrTREp.png should have url https://imgur.com/zvrTREp.png

Navigating in chrome browser to https://www.howtographql.com/?v1 gives NET::ERR_CERT_AUTHORITY_INVALID

• First working version
• Styling
• Iterate authentication

Caption not centered below image

What it should communicate

• THE entrypoint for learning GraphQL
• Target audience: Frontend + backend developers
• Covers every level: From beginner level to building advanced applications
• 3 segment content: 1) GraphQL 2) Frontend 3) Backend
• Rich content format: Detailed text + video courses & Code examples

Challenges

• Mobile/Responsive design
• Show enough content so it seems comprehensive but not overwhelming

Sections/Elements

• Hero: Communicate message + CTA (GraphQL, Frontend or Backend)
• First GraphQL query (probably the first time a person runs a GraphQL query -> makes curious -> CTA GraphQL)
• Framework/technology overview
• For the community by the community
• Content overview (outline for all (or most important) tracks)

Draft

• instruction blocks in the content should be visually marked so that readers can potentially skip content and only follow the instructions if they want to get through quicker
• code blocks should have a way to be annotated, e.g. with the file name where that code is located
• there should be two kinds of code blocks, one that communicates that the user needs to paste the contents in their own code, the other one communicates that this is example code that the user doesn't have to take any action on

"This is a special GraphQ object that gets passed to all resolvers"

should be "GraphQL" instead of "GraphQ"

• find collaborators

The last line of the Queries: Loading Links chapter of the React + Apollo tutorial reads:

That’s it! Go ahead and run yarn start again. You should see the exact same screen as before.

But as no mutations have been executed as part of the chapter, the content of the response to the query is an empty list of links: {"data":{"allLinks":[]}}, so the 2 links provided as mock data are no longer displayed.

Content

• GraphQL
• Frontend
  • React + Apollo
  • React + Relay
  • Expo + Apollo
  • Vue + Apollo
  • Angular + Apollo (minimal)
• Backend
  • Express / Apollo tools
  • Graphcool
  • Ruby/Rails
  • Scala/Sangria (Feedback from @OlegIlyenko
  • Python
  • Java

Format

• Final headlines (for sidenav)
• Description blurb to get feedback #20

On the second lesson of the Graphcool tutorial the graphcool status command is taught after the graphcool push command has likely been put into the learner's console. This might stop them from seeing what graphcool status will output. I think if you are going to include the graphcool status command in this tutorial, which I think makes sense, it'd be the best learning experience if they were introduced to it before they push their data off to the server.

I am willing to come up with a few changes here if you think this would be a good change.

/graphql gives a 404 not found in 'Queries' lesson.

At "Install Dependancies" install command

npm install —save express body-parser graphql-server-express graphql-tools graphql

should have ascii dash - before save, so should be,

npm install -save express body-parser graphql-server-express graphql-tools graphql

This brings up a different problem: In a GraphQL query where we ask want to retrieve information about a Child but only have a Person type to work with, how do we know whether we can actually access this field?

I think maybe the correct would be:
This brings up a different problem: In a GraphQL query where we ask to retrieve information about a Child but only have a Person type to work with, how do we know whether we can actually access this field?