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
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
>