1237032 - Refactor introductory material along the lines of the mozlando brownbags

Status: RESOLVED FIXED

(Taskcluster :: Services, defect)

Description

[Dustin J. Mitchell [:dustin] (he/him)]

The brownbags provided a nice model of the different perspectives users of taskcluster might take, and we should refactor our introductory material to match.

Comment 1

[Dustin J. Mitchell [:dustin] (he/him)]

I made some decent progress on this over the long weekend:
  https://github.com/djmitche/taskcluster-docs/tree/reorg
  http://docs.taskcluster.net.s3-website-us-east-1.amazonaws.com/

I got a little carried away and instead of hacking on the Jekyll stuff, rewrote the generation in JS.  This is still rough, but largely finished.  It involves:

 * dividing the docs up into tutorial, presentations, manual, and reference
   * the tutorial pages each have a set of "Next Steps" links at the
bottom, that take you to other tutorial pages, in a "hypertext" or
"choose your own adventure" fashion
   * the manual has a nice TOC based on the directory structure, with
convenient next/up/prev links
   * the services similarly have a nice TOC

 * `gulp publish` will publish to S3
   * plan is to hook this up to taskcluster-github, with the option to
push PR builds to a PR-specific bucket (this isn't as easy as it
seems)
   * plan is to front this with cloudfront so
https://docs.taskcluster.net works (and probably schemas.t.n and
references.t.n too)

 * for hacking on the docs, there's a local webserver that basically
emulates S3, serving from memory. pokey but functional.

 * redirects are in place for existing URLs, so awesomebars can keep
up - see `curl -v http://docs.taskcluster.net.s3-website-us-east-1.amazonaws.com/auth`
   * I'm a little bummed these are 301's, since it precludes ever
using those paths again, but it's OK

The rough bits are in TODO.txt.

Comment 2

[Dustin J. Mitchell [:dustin] (he/him)]

I want to use something like
  http://getbootstrap.com/examples/justified-nav/
for the index.  The kind of marketing site with three columns: "Free", "Small Business", "Enterprise" or whatever.  I'm happy to hear about other, better examples to copy from.

@Eli, if you have thoughts on any of this, I'm happy to hear them.

Comment 3

[Dustin J. Mitchell [:dustin] (he/him)]

TODO
====

* strip task-inspector stuff & dependencies
* collapsable TOC menus
* accessibility
* responsive
* generate bundle.js via gulp?

Reference
----

* Ensure all services are listed (even with stubs)
* Check headings on API docs (some have headings/intro in markdown file, some
  don't)

Tutorials
---------

* TC-101/102 into tutorial
  * developer workflow
  * intree-config
  * intree-image
  * tc-github
  * hooks
  * secrets
  * provisioner
  * clients??

Manual
------

* TC-201 into manual
  * Design slides -> devel
  * Use auth diagrams for authentication in manual
  * worker-types into worker-types intro
  * artifact uploads/downloads in queue manual
  * live logging in docker worker
  * interacive sessions in docker worker

Comment 4

[Dustin J. Mitchell [:dustin] (he/him)]

I moved the TODO above into but 1257945's gist, https://gist.github.com/djmitche/784b1b0e8d7220b4389f