- Fix broken links.
- Fix broken or undesirable Sphinx formatting.
- Fix internal references. There are many places that refer to plugins, configuration variables, etc that do not have Sphinx markup to generated internal references.
- Apply Sphinx markup standards (see below).
- Clarify and improve confusing passages, broken English, poor grammar, and fix general editorial concerns.
- Fix Table of Contents issues. The RTD Contents panel does not match up correctly with the intention of the content sections. Address navigation problems.
- Index. Figure out how to get Sphinx to generate an index.
I expect that during the editorial pass, you will find lots of problems. Please note these and we can choose to address them in subsequent passes.
Additional Reference Material
- Define and document Sphinx markup standards. For example, what markup should be used to refer to a plugin by name? What markup should be used for plugin parameters? The aim of this is to help the upstream team write consistent documentation so we can preserve the improvements.
- Define a standard terminology and markup for installation paths, etc. /etc/trafficserver, $PREFIX, $SYSCONFIG.
- Document all plugins.
- Document all records.config configuration settings. There are a couple of scripts that can identify settings that are undocumented or which have incorrect default values documented.
- Document all installed programs.
- Create a standard way to document performance metrics (at least data type, units, semantics, description). Document performance metrics.
Additional Administration Guide Material.
- Review the Inktomi Administration guide and incorporate any information that is still relevant. For example, this has a log of SOCKS documentation that is not present in the Sphinx documentation.
- Restructure Sphinx documentation to make finding information easier. Create new chapters, move sections into better locations, etc. Reconsider document flow and information presentation.
- Improve SSL configuration guide. There are lots of different ways to set up SSL; document common configurations. SNI, SAN, SSL tunnelling, intermediate certificate lookup, OCSP stapling, forward security, cipher suites, etc.
- New Traffic Server Monitoring guide. Using the metrics and logging reference material write a guide to monitoring Traffic Server. While this might reference specific tools (eg, logstash, graphite), the focus should be on guiding experienced operations engineers who are new to Traffic Server. What kind of information should be monitored and why? How can I extract the information that I should be monitoring?
The following JIRA tickets are relevant, and mostly covered by the lists above.
https://issues.apache.org/jira/browse/TS-987 Documentation for performance statistics
https://issues.apache.org/jira/browse/TS-510 API: Add documentation for HTTP Status code counters in stats (TS-509)
https://issues.apache.org/jira/browse/TS-436 Documentation for variable hardware sector size support
https://issues.apache.org/jira/browse/TS-2849 Add revalidation plugin docs
https://issues.apache.org/jira/browse/TS-2695 document how to monitor traffic
https://issues.apache.org/jira/browse/TS-2513 Missing SOCKS documentation
https://issues.apache.org/jira/browse/TS-2511 Document the 90% of Transparent Proxy use-cases
https://issues.apache.org/jira/browse/TS-2446 Document how to document
https://issues.apache.org/jira/browse/TS-2394 We need a performance tuning document
https://issues.apache.org/jira/browse/TS-2354 improve documentation about different type of timeouts
https://issues.apache.org/jira/browse/TS-1629 add documentation of important log files