search

codeceptjs / CodeceptJS

Supercharged End 2 End Testing Framework for NodeJS
http://codecept.io
MIT License
4.11k stars 724 forks source link

Documentation Resturcture #1279

Closed DavertMik closed 5 years ago

DavertMik commented 6 years ago

Let's discuss how can we improve documentation.

Currently we have the following sections:

Quickstart

Guides

Helpers

Reference

If you have ideas how to restructure the docs and make them better - please propose. Maybe we need new chapters or change contents of current ones? Please post your thoughts

elukoyanov commented 6 years ago

1st of all, we need much more clear and simple way to set up test infrastructure:

Maybe not all, but a few of it should be improved

elukoyanov commented 6 years ago

Maybe, make TS definition as separate typing package.

ftekmen commented 6 years ago

It can be added usage examples for CodeceptJS modules. I feel I can use CodeceptJS in a very flexible and custom way using modules but I do not know how I can. Maybe I can do this using source code but I am not at that level JS guru.

xt1 commented 6 years ago

The top nav is 

(Home) Quickstart  Video Guides  Helpers  Reference  Releases Support   Services  Next

From the point of view of a first-time visitor the first 3 are probably the most interesting / useful. Quickstart starts off well, but needs to call out the quickstarts for the different helpers in the nav, instead of just linking them at the bottom of the page.

Helpers is actually about the details of the different systems that Codecept supports - it is API reference and helpful hints mixed in.

Guides has lots of useful information (like Page Objects), but also has separate docs for each of the systems (Puppeteer, Nightmare etc). The whole BDD topic is hidden in here as well. Plugins and hooks, Advanced usage should probably move out into a separate advanced section, together with more info on the things mentioned above, like Docker etc.

A challenge for Codecept is that the helpers are very similar, but different enough to merit their own sections. Question is whether the helpers should drive the nav.

i.e. is

(Home)  Quickstart Concepts  Selenium   Nightmare  Protractor  Puppeteer  Appium   Reference  Releases Support   Services

a useful navigation scheme? Maybe there are too many helpers to really do it like this? Video would go under the general Quickstart. Concepts would collect all the stuff that is valid across all the helpers: Basics, PageObjects, BDD, Selenium and the rest would have menu items: QuickStart, Configuration, Guide, API Reference, TypeScript under Quickstart probably. Reference is pretty much the same. Docker could probably move to Concepts?

xt1 commented 6 years ago

Less radical navigation organization - move the videos to their appropriate pages, add a Concept nav item to collect generally useful info.

Quickstart

Concepts

Guides

Helpers

Reference

Releases Support Services

xt1 commented 5 years ago

I can re-org the docs as outlined above and write some stuff, make a pull request?

xt1 commented 5 years ago

Preview of where I'm at now - just moving content around to try to improve findability and structure.

http://xt1.org/codecept/

BTW: i really like the new look on the codecept.io site, but I'm not entirely sure about the side menus on both sides of the page.

DavertMik commented 5 years ago

@xt1

BTW: i really like the new look on the codecept.io site, but I'm not entirely sure about the side menus on both sides of the page.

The design is not mine, it's docusaurus. https://docusaurus.io So I had to stick to their decisions :( 2 sidebars and no dropdowns in topbar :(