Issue/309 docs table of contents

[thescientist13]

Description

Coming out of the 2020-03-10 meeting of the Package Maintenance team, on the topic of issue #309, the suggestion was that this comment on the suggestion of a Table of Contents for the docs in the repository be extracted out into its own PR.

Summary of Changes

1. Updated the docs/README.md to provide additional context and motivation on behalf of the team, and created a ToC that links to existing docs.
2. Created "stubs" for missing docs, that could become their own issues to track and can be authored independently and eventually promoted out of draft status.

Questions / Considerations

Just around docs in general...

1. Is there a threshold for a doc moving out of draft status?
2. Would there be any value in having a general format / convention around docs in terms of authoring / organization / structure?

[thescientist13]

Made follow up issues for the following topics in the list, either because they are new, or because it would be good to move them out of draft status:

• Repository Settings (new) - [docs] repository settings (new) #339
• Continuous Integration / Delivery (draft) - [docs] continuous integration / continuous delivery (draft) #340
• Workflows (draft) - [docs] workflows (new) #341
• Code of Conduct (draft) - [docs] code of conduct (new) #342
• Security (draft) - [docs] security guidelines (draft) #343
• Testing (draft) - [docs] testing guidelines (draft) #344
• Publishing Guidelines (draft) - [docs] publishing guidelines (draft) #345
• Support (draft) - [docs] package support (draft) #346
• Tools (draft) - [docs] tools (draft) #347

Depending on order of merges, we should probably include Dependency Management on this list as there is a PR open for adding it to the project.

Also missed out on tools.md, so added that to the ToC.

---

One question: is there criteria documented for what is considered a document in draft status vs not in draft status? In other words, how does a draft actually move out of that status, if it is in it?

[mhdawson]

LGTM

[BethGriggs]

LGTM

[Eomm]

Merging

more than 7 days from 4th approve and no blocking review

One question: is there criteria documented for what is considered a document in draft status vs not in draft status? In other words, how does a draft actually move out of that status, if it is in it?

I think we could could think to drafts as v0.x and not major released yet 😅 Usually it means that there is still discussion on them and those docs did not receive a complete consensus.

Would there be any value in having a general format / convention around docs in terms of authoring / organization / structure?

Right now there is not a shared structure (like file name in UPPERCASE and some in lower), it would be good have it since we are writing a lot of docs 👍