1257945 - [tracker] Docs Approachability Project

Status: RESOLVED FIXED

(Taskcluster :: Services, defect)

Description

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

We'd like to reorganize our docs a little bit to be more approachable and more discoverable.

Per discussion with Brian, that means

Improving the consistency of where types of information are available, so we're not left saying "that's somewhere on teh docs site" and not being able to find it (which happens to me all the time)

Updating the "home page" to give newcomers a better direction to go

Thinking carefully about audiences and sub-audiences, and providing just the information required:

 - users (running tasks in taskcluster)
   - from a repo
     - from github
     - from gecko
     - from gaia
   - injecting tasks from another service
 - api consumers
 - developers

This bug will track general progress toward that goal, and serve as a point for me to link to a gist with notes about it :)

Comment 1

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

Anti-goals for this ticket:

 * refactoring service doc generation (not everything is service-associated!)
 * rewriting doc generation in something other than Jekyll

Comment 3

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

I updated https://gist.github.com/djmitche/784b1b0e8d7220b4389f to include the TODO from some sub-bugs.

I'll try to knock out one of these items per week, more or less.  Everyone's invited to help! :)

Comment 4

[Akshay Jain]

Hello Dustin, Would I be of any help to you for reorganizing the docs?

Comment 5

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

Akshay: I have completed most of the reorganization, but the TODO I linked in comment 3 contains a bunch of tasks that still need to be done.  If you have frontend experience, then perhaps making the table-of-contents sidebars more interactive would be interesting to you?

Comment 6

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

This tracker is just serving as a link to the gist, so let's close it