Traffic Control Doc's Proposal

[Dewayne Richardson <de...@apache.org>]

I've been going through the Traffic Ops API doc's and revamping them with
Swagger and noticed this trend with our documentation.   "Guides" (Howto's,
Installs, Developer's)  growing because they are easier to maintain
(because they are less fancy) as markdown files in the Github project.  My
concern is the RST equivalents here:
http://traffic-control-cdn.readthedocs.io/en/latest/development/index.html
are going stale and they are also being duplicated in the markdown files.
I also worry that the markdown files aren't surfaced properly to our
community because there is valuable information in them as well.

Therefore I propose the following documentation "rules of thumb":

1. Howto's, Installs, Developer/Admin Guides are done in Markdown but have
RST links (or some reference to an index page to surface all of them)
2. High level informative documentation like API docs, and Traffic Control
features are done in RST as we have been to surface that information for
"Users of Traffic Control"

Please provide your feedback,

-Dew


Here is a quick list of the Markdown files I've found in the project so far:


./misc/git/README.md
./CODE_OF_CONDUCT.md
./experimental/traffic_router_golang/README.md
./test/traffic_ops_cfg/Readme.md
./test/router/dnssec/Readme.md
./test/router/Readme.md
./CHANGELOG.md
./traffic_portal/v1/README.md
./traffic_portal/test/end_to_end/README.md
./traffic_portal/README.md
./traffic_portal/build/README.md
./traffic_monitor_java/README.md
./traffic_monitor/tools/testcaches/README.md
./traffic_monitor/README.md
./traffic_server/plugins/astats_over_http/README.md
./traffic_server/README.md
./README.md
./traffic_ops_db/pg-migration/README.md
./traffic_ops/experimental/goto/README.md
./traffic_ops/experimental/auth/README.md
./traffic_ops/experimental/server/README.md
./traffic_ops/experimental/webfront/README.md
./traffic_ops/INSTALL.md
./traffic_ops/README.md
./traffic_ops/testing/compare/README.md
./traffic_ops/testing/api/docker/README.md
./traffic_ops/testing/api/README.md
./traffic_ops/build/README.md
./traffic_ops/client_tests/README.md
./traffic_ops/traffic_ops_golang/README.md
./traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
./CONTRIBUTING.md
./BUILD.md
./build/README.md
./infrastructure/docker/README.md
./infrastructure/docker/build/README.md
./infrastructure/test/integration/README.md
./infrastructure/test/README.md
./traffic_router/core/src/test/resources/Readme.md
./traffic_router/neustar/README.md

Re: Traffic Control Doc's Proposal

[Jeremy Mitchell <mi...@gmail.com>]

Can you clarify what a "howto" is?

Yes, it looks like our README's are a bit out of control. What if we
consolidated them like such:

./README.md <-- this one links to general information about TC
(readthedocs) and also links to the following:

./traffic_portal/README.md
./traffic_monitor/README.md
./traffic_ops/README.md <-- this links to ./traffic_ops_db/README.md
./traffic_router/README.md
./traffic_server/README.md
./traffic_stats/README.md

^^ each of these readme's include 3 things at the very least:

- How to install
- How to develop
- A link to component info found in readthedocs (rst)

Jeremy

On Wed, Apr 4, 2018 at 9:48 AM, Dewayne Richardson <de...@apache.org>
wrote:

> I've been going through the Traffic Ops API doc's and revamping them with
> Swagger and noticed this trend with our documentation.   "Guides" (Howto's,
> Installs, Developer's)  growing because they are easier to maintain
> (because they are less fancy) as markdown files in the Github project.  My
> concern is the RST equivalents here:
> http://traffic-control-cdn.readthedocs.io/en/latest/development/index.html
> are going stale and they are also being duplicated in the markdown files.
> I also worry that the markdown files aren't surfaced properly to our
> community because there is valuable information in them as well.
>
> Therefore I propose the following documentation "rules of thumb":
>
> 1. Howto's, Installs, Developer/Admin Guides are done in Markdown but have
> RST links (or some reference to an index page to surface all of them)
> 2. High level informative documentation like API docs, and Traffic Control
> features are done in RST as we have been to surface that information for
> "Users of Traffic Control"
>
> Please provide your feedback,
>
> -Dew
>
>
> Here is a quick list of the Markdown files I've found in the project so
> far:
>
>
> ./misc/git/README.md
> ./CODE_OF_CONDUCT.md
> ./experimental/traffic_router_golang/README.md
> ./test/traffic_ops_cfg/Readme.md
> ./test/router/dnssec/Readme.md
> ./test/router/Readme.md
> ./CHANGELOG.md
> ./traffic_portal/v1/README.md
> ./traffic_portal/test/end_to_end/README.md
> ./traffic_portal/README.md
> ./traffic_portal/build/README.md
> ./traffic_monitor_java/README.md
> ./traffic_monitor/tools/testcaches/README.md
> ./traffic_monitor/README.md
> ./traffic_server/plugins/astats_over_http/README.md
> ./traffic_server/README.md
> ./README.md
> ./traffic_ops_db/pg-migration/README.md
> ./traffic_ops/experimental/goto/README.md
> ./traffic_ops/experimental/auth/README.md
> ./traffic_ops/experimental/server/README.md
> ./traffic_ops/experimental/webfront/README.md
> ./traffic_ops/INSTALL.md
> ./traffic_ops/README.md
> ./traffic_ops/testing/compare/README.md
> ./traffic_ops/testing/api/docker/README.md
> ./traffic_ops/testing/api/README.md
> ./traffic_ops/build/README.md
> ./traffic_ops/client_tests/README.md
> ./traffic_ops/traffic_ops_golang/README.md
> ./traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
> ./CONTRIBUTING.md
> ./BUILD.md
> ./build/README.md
> ./infrastructure/docker/README.md
> ./infrastructure/docker/build/README.md
> ./infrastructure/test/integration/README.md
> ./infrastructure/test/README.md
> ./traffic_router/core/src/test/resources/Readme.md
> ./traffic_router/neustar/README.md
>