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 <[email protected]> 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 >
