search

mantoni / mochify.js

☕️ TDD with Browserify, Mocha, Headless Chrome and WebDriver
MIT License
346 stars 57 forks source link

Rewrite: Documentation #265

Open m90 opened 2 years ago

m90 commented 2 years ago

If we want to flip the switch and bring the rewrite to a 1.0.0 we'll also need documentation. I'd be happy to contribute here as well, so I'll just ask some questions:

READMEs, Wiki, Docs site?

I would assume the Rewrite requires some more detailed docs than the original Mochify. How far do we want to go here? Do we put everything into READMEs in the repository, do we start using the repo's wiki or do we even go for a simple docs site? I have to admit I quite enjoy reading non-README documentation by now, but I also see the maintenance burden this brings. Wikis are odd, but that's very subjective.

All-in-one or per module

Is there a single entrypoint for all @mochify documentation or does each package get its own docs? I think having everything in one place would be nice, but this of course creates the problem of not having docs (unless you start scripting) on npmjs.org (although I have to admit that I personally will never read these there but always click through to the backing repository)

Scope of driver docs

What's the scope of driver specific documentation? Does this really only cover the driver itself or would it also tell you about how to use the driver in conjunction with Mochify itself?

CLI docs

Do CLI docs live in the top level README or do they go into the cli package?

Top level README

What should someone who has just read the top level README be able to take away? Get Mochify set up somehow or find answers to detailed questions as well?

CLI help

Right now --help does not really yield anything helpful although it should:

Options:
      --help           Show help                                       [boolean]
      --version        Show version number                             [boolean]
      --config                                                          [string]
      --driver                                                          [string]
      --driver-option
  -R, --reporter                                                        [string]
      --bundle                                                          [string]
      --esm                                                            [boolean]
      --serve                                                           [string]

How "fancy" should this get? Do we want to include usage examples in the output (which I like a lot personally)?

mantoni commented 2 years ago

Some basic documentation in each projects README is important for npm, but those can also point at a website.

I have a rough idea in my head which would be a bit of a mix of your suggestions. The result would be a website that is generated from content in markdown files from the individual projects, stitched together by the parent project. I'll play a bit with those thoughts and see if it gets us anywhere.