You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Jon Sime <js...@omniti.com> on 2015/02/02 21:45:17 UTC
Documentation restructuring
I've been putting together a restructuring proposal for the current guides
as part of the overall documentation cleanup/standardization effort. A
working doc (with commenting enabled - please take full advantage) is here:
https://docs.google.com/document/d/1qlf_N03wGeDeC3Hg9d0Xsl00JY2mIQ5IX5oe65FeWx0/edit?usp=sharing
Feedback, corrections, criticism, and comments would all be most welcome.
For comparison's sake, the doc includes the current section headings from
the existing documentation before listing the proposed new layout. The
largest points:
- Number of guides reduced to 2 (and a half): an Administrator's Guide for
system admins, users, and others deploying (ATS in their infrastructure (or
considering doing so), and a Developer's Guide for those working on the ATS
code itself or writing plugins for it. Plus the short Getting Started
half-guide for people new to ATS just looking to get it up and running in
30 minutes to test things out in a basic configuration.
- Existing Programmer's Guide, Arch & Hacking, and API Reference all get
combined into the Developer's Guide.
- Existing Administrator's Guide acquires the bulk of the Reference Guide
(the Configuration File Reference, Command Reference, and Plugin Reference
sections).
- Sections, particularly in the Admin Guide, are reordered to be more
topically-aligned with each other, and to reduce the instances where
related information is found in more than one non-adjacent section.
Re: Documentation restructuring
Posted by Jon Sime <js...@omniti.com>.
Certainly a fair point. I've been looking at the Administrator's vs.
Developer's guides as largely distinct entities (given that the audiences
for each are pretty different). However, the Appendices was something that
only felt slightly more at home in the admin guide, but not exactly a
perfect fit.
There's no reason the Appendices could not be included in both guides. Same
content, same RST source files, just listed in both guides' TOCs.
Or maybe it makes more sense to have an all-inclusive 3-part "Apache
Traffic Server Manual" that has each guide as one part, with a single
Appendices section at the end; as opposed to a set of documentation
consisting of three separately-treated guides. Doing that wouldn't really
be much of a change to the proposed structure of each guide, it would be
more a matter of how the three parts are packaged/presented together, I
think, and would make it cleaner to have a common Appendices section tucked
in at the end, and still structurally related to both guides.
On Mon, Feb 2, 2015 at 9:44 PM, Bin Zeng <bz...@linkedin.com.invalid> wrote:
> Hi Jon,
>
> Good work! The new structure looks much better than the current version.
> It is better organized into three parts:
> Getting started, Administrator's guide, and Developer's guide. I have only
> one comment. The appendices do not really
> fall into only Administrator's guide. It is for both administrators and
> developers. Besides, most people expect
> to see appendices at the very end of a book/docs. It is kind of weird to
> hide it in the middle. Other than that, it looks to me.
>
> Just my 2 cents.
> Bin
>
> ________________________________________
> From: Jon Sime [jsime@omniti.com]
> Sent: Monday, February 02, 2015 12:45 PM
> To: dev@trafficserver.apache.org
> Subject: Documentation restructuring
>
> I've been putting together a restructuring proposal for the current guides
> as part of the overall documentation cleanup/standardization effort. A
> working doc (with commenting enabled - please take full advantage) is here:
>
>
> https://docs.google.com/document/d/1qlf_N03wGeDeC3Hg9d0Xsl00JY2mIQ5IX5oe65FeWx0/edit?usp=sharing
>
> Feedback, corrections, criticism, and comments would all be most welcome.
> For comparison's sake, the doc includes the current section headings from
> the existing documentation before listing the proposed new layout. The
> largest points:
>
> - Number of guides reduced to 2 (and a half): an Administrator's Guide for
> system admins, users, and others deploying (ATS in their infrastructure (or
> considering doing so), and a Developer's Guide for those working on the ATS
> code itself or writing plugins for it. Plus the short Getting Started
> half-guide for people new to ATS just looking to get it up and running in
> 30 minutes to test things out in a basic configuration.
>
> - Existing Programmer's Guide, Arch & Hacking, and API Reference all get
> combined into the Developer's Guide.
>
> - Existing Administrator's Guide acquires the bulk of the Reference Guide
> (the Configuration File Reference, Command Reference, and Plugin Reference
> sections).
>
> - Sections, particularly in the Admin Guide, are reordered to be more
> topically-aligned with each other, and to reduce the instances where
> related information is found in more than one non-adjacent section.
>
RE: Documentation restructuring
Posted by Bin Zeng <bz...@linkedin.com.INVALID>.
Hi Jon,
Good work! The new structure looks much better than the current version. It is better organized into three parts:
Getting started, Administrator's guide, and Developer's guide. I have only one comment. The appendices do not really
fall into only Administrator's guide. It is for both administrators and developers. Besides, most people expect
to see appendices at the very end of a book/docs. It is kind of weird to hide it in the middle. Other than that, it looks to me.
Just my 2 cents.
Bin
________________________________________
From: Jon Sime [jsime@omniti.com]
Sent: Monday, February 02, 2015 12:45 PM
To: dev@trafficserver.apache.org
Subject: Documentation restructuring
I've been putting together a restructuring proposal for the current guides
as part of the overall documentation cleanup/standardization effort. A
working doc (with commenting enabled - please take full advantage) is here:
https://docs.google.com/document/d/1qlf_N03wGeDeC3Hg9d0Xsl00JY2mIQ5IX5oe65FeWx0/edit?usp=sharing
Feedback, corrections, criticism, and comments would all be most welcome.
For comparison's sake, the doc includes the current section headings from
the existing documentation before listing the proposed new layout. The
largest points:
- Number of guides reduced to 2 (and a half): an Administrator's Guide for
system admins, users, and others deploying (ATS in their infrastructure (or
considering doing so), and a Developer's Guide for those working on the ATS
code itself or writing plugins for it. Plus the short Getting Started
half-guide for people new to ATS just looking to get it up and running in
30 minutes to test things out in a basic configuration.
- Existing Programmer's Guide, Arch & Hacking, and API Reference all get
combined into the Developer's Guide.
- Existing Administrator's Guide acquires the bulk of the Reference Guide
(the Configuration File Reference, Command Reference, and Plugin Reference
sections).
- Sections, particularly in the Admin Guide, are reordered to be more
topically-aligned with each other, and to reduce the instances where
related information is found in more than one non-adjacent section.