cubing.js icon indicating copy to clipboard operation
cubing.js copied to clipboard

Documentation: Added "Drafts" folder and "Documentation Guidelines.md"

Open dunkOnIT opened this issue 4 years ago • 0 comments

Implicit in some of what I wrote in this PR are a number of proposals which I believe warrant input from @lgarron and @rokicki. For the sake of expediency, I wrote them as declarative statements in Documentation Guidelines, but everything here represents a proposal for discussion.

To start, I suggest we start distinguishing between 2 kinds of documentation:

  • API Reference - describes the usage of the functions/modules which are exposed through the cubing.js library
  • Long-form documentation - README, tutorials, CONTRIBUTING.md - anything that looks more like prose than function definitions. When I use the general term "documentation", I am referring to both of these.

Overall, these proposals aim to do 3 things:

  1. Present a roadmap for addressing the current documentation backlog
  2. Prevent the growth of the documentation backlog by encouraging API reference documentation "as we go"
  3. Introduce the concept of "Draft" documentation to make it easy to "jot down" long-form documentation as it comes to us (as this document did to me), rather than feel that if we are going to write any documentation at all it has to be perfect.

Proposals:

(a) All new modules/functions added should only be accepted/considered complete if they are accompanied by API Reference documentation - in line with (2) above (b) Store draft documentation in /docs/draft, so that the drafts people come up with are shared and can be taken forward by someone else if needed (c) Not backtick technical references when they include links, to prevent ambiguity (this comes out of my experience of trying to browse the README (d) See Documentation roadmap section for my proposed roadmap for tackling the current documentation backlog

Discussion welcome, hence the draft nature of this PR. Once/if considered by both of you and agreed, we can merge.

dunkOnIT avatar Aug 29 '21 14:08 dunkOnIT