Closed
Bug 1362074
Opened 8 years ago
Closed 8 years ago
Refactor the manual
Categories
(Taskcluster :: Services, enhancement)
Taskcluster
Services
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
Assignee | ||
Comment 1•8 years ago
|
||
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 :)
Comment 2•8 years ago
|
||
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
Assignee | ||
Updated•8 years ago
|
Status: NEW → RESOLVED
Closed: 8 years ago
Resolution: --- → FIXED
Updated•6 years ago
|
Component: Documentation → Services
You need to log in
before you can comment on or make changes to this bug.
Description
•