Closed Bug 1362074 Opened 8 years ago Closed 8 years ago

Refactor the manual

Categories

(Taskcluster :: Services, enhancement)

enhancement
Not set
normal

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: dustin, Assigned: dustin)

Details

The TC manual should be the "middle ground" between the tutorial (which focuses on "getting your hands dirty" without a lot of detail) and the reference (which is statements of facts). The manual should describe the organization and model of TC so that a reader can feel like they "understand" the system and can place the reference material in context cover common scenarios that cross service boundaries (indexed artifacts at stable URLs, decision tasks, ..) be readable in a linear fashion details in https://github.com/taskcluster/taskcluster-rfcs/issues/57 progress in https://github.com/taskcluster/taskcluster-docs/compare/master...djmitche:new-manual?expand=1
http://pyvideo.org/pycon-us-2017/how-documentation-works-and-how-to-make-it-work-for-your-project.html divides documentation into four types: - tutorial - reference - how-to guides - discussion and suggests distinguishing those carefully. I think we're most of the way there, although I'm including both discussion and how-to guides in the manual/ section. The guides are in manual/using. I think this flows reasonably well, but I could easily be convinced to make a new top-level documentaiton book :)
Commits pushed to master at https://github.com/taskcluster/taskcluster-docs https://github.com/taskcluster/taskcluster-docs/commit/78a9154060ca5f80df8aa6d79e22a6fbd35f3fb5 Bug 1362074: Completely re-draft the manual Rewrite the manual based on a new planned table of contents, organized in a more narrative fashion: discuss tasks, discuss task execution, discuss Taskcluster's design, then include a bunch of how-to articles for common use cases. This fixes taskcluster/taskcluster-rfcs#57. https://github.com/taskcluster/taskcluster-docs/commit/2c19514f7db518519897bd5beda7af500fd2d9ed Merge pull request #186 from djmitche/new-manual Bug 1362074: Completely re-draft the manual
Status: NEW → RESOLVED
Closed: 8 years ago
Resolution: --- → FIXED
Component: Documentation → Services
You need to log in before you can comment on or make changes to this bug.