docs(quickstart): update to new doc design (TS and Dart)

[chalin]

Note: it is best to view TS .jade file changes while ignoring whitespace.

The quickstart chapter was updated to conform to the new docs design (using Jade blocks).

• TS: Jade file updated to support new docs design. Also other kinds of edits; e.g., the prose is more compact, showing the handful of config files in via a makeTab. This new shorter version (once explanations are hidden) feels more like a QuickStart guide :).
• Dart. Recreated prose as extension of TS prose. Code was updated to conform to the organization of the app given on the TS side. I.e., the app component was factored out into its own file. E2e tests pass :).

[Foxandxss]

I love what you did with the prose.

What I am a bit wary about is that now we are mixing a lot of markdown with jade. Sometimes we have links in markdown, sometimes in jade, headers in markdown, sometimes in jade... We need to make our mind. I don't really want to me "writing markdown" but having also to use jade.

[chalin]

Glad you like it.

Yes, I have been looking for ways to avoid using too much Jade vs markdown. The limitations we currently face are:

1. While Jade string interpolation #{...} works in markdown, tag interpolation #[...] does not. This is a limitation because mixins can only be interpolated via #[...].

2. The smallest unit of markdown that can be used in conditionals is the paragraph. E.g.

:marked
  some initial text
- if (some condition)
  :marked
    conditionally included text
:marked
  more text

Renders as separate paragraphs like this:

some initial text
conditionally included text
more text

Which is fine when each fragment is meant to be a stand alone paragraph, but sometimes, the prose to be conditionally included is just a word/phrase/statement within a paragraph. Like this:

some initial text conditionally included text more text

To get intra-paragraph conditional inclusion of text requires that we fall back to using Jade elements. It used to be worse, but as I learn more Jade I have been finding better ways of avoiding mixing markdown and Jade elements. Hopefully that will get better over time.

---

All that being said, the more I work with it the more I find the Jade readable: e.g.

:marked
  # Title

  Text text text text
  Text text `text` text

in Jade becomes

h1 Title
p.
  Text text text text
  Text text #[code text] text

Which seems as readable, but with one less level of indentation :).

[wardbell]

Thanks Patrice!

I was skeptical at first but I think this works out pretty well.

I fixed broken links and made a few other adjustments (including squashing) before merging.

[chalin]

@wardbell: it would be much easier for @kwalrath and me to follow the adjustments (beyond copyedits) you make if they are in a separate PR. Or, just make inline comments to the original PR source files and then I can make the edits.

That way it gives us a chance to discuss edits (beyond simple copyedits). Generally your edits are good (e.g. fixed links), but I do have some questions/remarks: e.g.,

• Why did you choose to exclude the "DOWNLOAD THE SOURCE" call out for Dart? Is it because you want Dart users to work harder ;).
• You renamed "Step 0" to "Prerequisite", but with the new title, this clashes with the fact that we instruct users to "install" s/w rather than just list it. Btw, the "Step 0" convention, is a convention adopted in most Dart tutorials.
• You repositioned the "DOWNLOAD THE SOURCE" to be immediately after the "Install Node.js..." which could mislead some readers. I suggest either putting this callout before the "Step 0/Prerequisite" step or at the start of Step 1.
• FYI, makeExcerpt will, by default, have no line numbers; so to appending (format=".") is unnecessary.
• Speaking of line numbers, it has been my understanding that excerpts never show line numbers (to avoid confusing users), but that full examples do (so that users can more easily make reference to a specific line in the source if they wish to comment on it). Do you agree?

[wardbell]

Sorry. I thought it was easy as a separate commit and you could diff.

Step 0 may work for Dart but not the much broader audience. Also, unlike other steps, it is a one time step AND a prerequisite for the QS repo. I'm afraid I must insist on this point.

Download exclusion was indeed to hinder Dart development. 😃.

Repositioning was because the prerequisite is for BOTH download and subsequent steps. Please keep.

Excerpts could have line numbers and should if they are long". I haven't defined long but rule of thumb is >10 lines

[kwalrath]

Line numbers in excerpts make sense to me only if they reflect the actual line numbers in the file. Otherwise, I think it's very confusing.

To me, line numbers seem relevant if you're actually referencing them in the text. Otherwise, they just take up space.

[chalin]

That has been my take on line numbers too.

@wardbell : I'm ok with all of the changes you suggest I keep. As for the download exclusion, I mistakenly though that you had excluded it for some reason--- the Dart .jade file comment exclude this section from Dart threw me off. I understand now is that you were just focused on getting the TS prose done. I'll reintroduce the download for Dart.

[wardbell]

Interesting. I never thought of them as referring to actual fille lines... because they almost never do. Too many docregion exclusions.

Rather they facilitate the dialog that begins on line #42 where you add the frames..._

Otherwise, I'd never use.

Let's keep until we see how Naomi feels.