search

gstroup / apimocker

node.js module to run a simple http server for mock service responses.
MIT License
280 stars 80 forks source link

Document suggestion #87

Open MarqueIV opened 6 years ago

MarqueIV commented 6 years ago

Not sure if you'd agree with this change, so I wanted to ask before submitting a PR.

Currently in your documentation, you have one large config file, the further down the page, you describe its various configuration options. The issue is as you're reading the descriptions of how to configure it, you're nowhere near the actual configuration itself. Additionally, on more than one occasion, I have found myself confused by a disparity between the documentation and the config file, before realizing I was looking at the wrong section in the config file that had similar names.

My suggestion would be, for each feature/area you are describing (e.g. templating, switching, etc.) copy that specific config example right to that area. That way a user won't have to constantly scroll back and forth.

Another thing that would help is a sort of TOC area up top that links down to the individual sections. If you want to go to templating, click that entry and you're scrolled right down.

That would address the limitations of the single-page documentation needed for using GitHub.

Anyway, I wanted to ask if you thought that's a good idea before making the change and submitting a PR because it's not a simple thing and will require an effort to separate out, and if you don't agree, it would be an impractical use of time.

ferrerod commented 6 years ago

Hi Marque, I agree a TOC would be beneficial. I also agree (if done right) that having examples organized by each section of the config could be valuable for new users. Obviously, until we see the PR, we can't judge if you've done a great job or just made it harder to follow :-)

gstroup commented 6 years ago

Yes, I agree that the documentation could use some work. As the project has grown, the documentation has also grown, but it's not very organized. TOC sounds good. Some smaller examples might be good. I was thinking of possibly adding an "examples" directory, containing config files demonstrating different features. I've seen this pattern in other OSS projects. Anyway, if you have the time, I would be happy to review a PR and merge it in. Thanks!

MarqueIV commented 6 years ago

I haven't forgotten about you guys. Just been slammed with other tasks. Promise I'll come back and update this soon. :)