(enhancement) Make the documentation more accessible

[phndiaye]

First of all, thanks a lot for maintaining this project! It's really easy to use and enables so much :)

What I'm proposing here is merely a reorganisation of the documentation and possibly moving it to a website for better discoverability. Currently, I find the README file a bit hard to read with lots of information (and not always in the "right" order IMO). For example, the setupFactoryGuy function is mentioned in the last sections while in real usage, it's the first function called by any tests. Of course, the addon is usable in development and production environments, but I think that's not the common usage.

So, a possible summary could be:

• Getting Started
  • Presentation of the project
  • Why Factories (vs Fixtures) ?
  • Features (just a bulletpoint list of the main features: mocking ember data requests, creating factories, scenarios, mocking any HTTP request, mocking failures, etc.)
  • Usage: a snippet of the most basic test using FactoryGuy (setup, a mockFindRecord, an assertion)
• Quickstart
  • Installation (example w/ ember install, with npm and with yarn)
  • How it works (more details about how it uses Pretender to register the ember data requests and sends the mock responses when those requests occur)
  • Setting up for tests (present the setupFactoryGuy function)
  • Setting up for other environments (this can group both development and production imo)
  • Present Factories (high level description + link to the dedicated section)
  • Present Mock methods (high level description + link to the dedicated section)
• Factories
  • Repeat their purpose
  • Defining factories
  • Using factories
• Mocking requests (go through the functions signatures + snippets)
  • mock
  • mockFindRecord
  • mockFindAll
  • (all remaining functions)
• Advanced Usage
  • Shipping Factories in an addon
  • Custom API formats
  • Using the Pretender instance directly
  • Ember Data Model Fragments
  • Ember Django Adapter
• Tips and tricks

As noticed, this is merely a reorganisation of the existing with lots of sub-sections for describing the purposes, but the content is already here. I might have missed some sections so feel free to comment that.

About the website, it could be generated using docsify and hosted using Github Pages. At the moment, it can build from the README.md file and here is the result:

https://www.loom.com/share/bab6ae84286e41099e7de6be56bf684d

And of course I'm totally willing to work on this if it interest others 😄

[patocallaghan]

@phndiaye yes I completely agree. I find the docs in their current format hard to read and find what you are looking for.

What you've outlined in the issue description seems like a really good start. What timezone are you based in? Would you be up for video chat to figure out next steps? You can find me on the Ember Discord as patocallaghan to chat more

[phndiaye]

@patocallaghan thanks for the reply :) i'm on the UTC+1 timezone and i'm totally up for a chat about this. Sending you message on the Ember Discord