Readme is impractical

[vasilakisfil]

Thanks for the gem.

But the readme is so fancy that is impractical. May I ask why there are pictures instead of regular code blocks which you can copy/paste them ?

[richpeck]

I was experimenting with the pictures.

I'll change the Readme in the next update, unless you'd like to submit a PR?

[vasilakisfil]

ok. I don't want to ruin your style, everyone has its own and I think having such fancy pictures in the beginning of the Readme is unique and funny. I am mostly interested in the practical part, the code blocks.

I ll try to find some time during the weekend.

[richpeck]

Yep - I'm not bothered, I put them on all the things I do. I do agree though that they get in the way for many aspects -- I was going to upgrade the Readme when I had to do a new update but haven't got around to it yet

[invalidusrname]

This README is awesome. Maybe a little lense flare on the logo would make it 💯 .

I tend to copy/paste things when coming across a new projects, so I agree it'd be helpful if the code blocks were text instead of images.

[richpeck]

Thanks bud - yes I'll change it later. In terms of copy/paste, yes I do this too - I will be updating the readme after I finish a project I've been involved with.

[clveranis]

If I could throw my 2 cents in.. I'd really like to use this gem but I have no practical idea as how to. The README has links to "install/setup/config" but they just link to different sections with pictures. As far as I can tell, everything in the README lends to what the gem does but not what I need to do to get it working.

I think the look is creative and it truly showcases the gem and makes me want to use it but it's getting frustrating having to search all over on how to actually get it working. I understand
that you just install it and it runs but there's no clear guide on how to customize the exceptions_controller and other things that go on behind the scenes to make work in the way that I envision.

I'm not going to give up on trying to get it working but if the README at least included clear step-by-step instructions just to get it off the ground, that would be a major step forward imo. But from everything that I have seen/heard so far, this gem looks awesome, now I just need to get it functional for my needs.

[richpeck]

Hey man, thank you for the feedback

The current readme was meant to be updated but lots of other stuff has taken precedent recently 😞 I'll be updating the Readme soon as well as the gem (had some other stuff to work on recently). I did intend to fix up the Readme but just haven't got around to it yet.

--

In terms of getting it working, you're welcome to email me directly at rpeck@frontlineutilities.co.uk for specific help if you need it. For a general overview, here's what you need to do:

• Add the gem to your Gemfile

• Once the gem installs (don't worry about precompiling assets because that's done automatically), it will just work in production. Your 40x error pages will be the same as your controller's layout and your 50x pages will be the custom layout provided in the gem (this will get a makeover next version).

• To get the Gem to show up in development, you will need to add the following to one of Rails' environment files (config/application.rb or config/environments/development.rb) ↴
  config.exception_handler = { dev: true }

• This will use exception handler in dev mode

• If you want to change any of the text that's shown by EH, you can add it to a new locale in config/locales/en.yml:

#config/locales/en.yml
exception_handler:
    not_found: "Text here"

This can be changed for any of the errors listed here (unfortunately, didn't get around to doing 40x/50x general error locales yet): https://gist.github.com/mlanett/a31c340b132ddefa9cca

For example, you may want to change the 500 error text, which is done with:

#config/locales/en.yml
exception_handler:
    internal_server_error: "Text here"

• To change the layouts etc, you're going to have to use one of the generators to copy over the various view/asset files (detailed the readme)

---

Again, if you need further support, you're very welcome to email rpeck@frontlineutilities.co.uk and I'll be able to give specific info on code etc

[clveranis]

@richpeck thank you very much for responding both in a timely manner and with an insightful answer! I'm in the process of developing an intricate app myself so I fully understand prioritizing important tasks efficiently, so no worries. My post was only to provide feedback on how to make it easier for first time users to implement it but more importantly, to customize it appropriately without detracting from any of its great features.

I'll be sending you an email with a couple quick questions so that I don't hijack this thread. Thank you again for taking the time to answer a question that I'm sure you've answered hundreds of times 👍

[kyleduck]

i appreciate the creativity, but the readme is overdone. i kept waiting for you to ask for my money. i'd be glad to pay because it's a useful gem, but hey.

your comments here should be the readme imo

also, why is the 5xx error page different than 4xx? the design won't fit with anybody's application. just let us handle that.

by the way, i've dropped nil in my 5xx series layouts in application.rb and it's still defaulting to your view....

[richpeck]

Firstly, thank you for taking the time to post, much appreciated.

kept waiting for you to ask for my money.

That's the world I come from so that's actually a compliment (thank you).

I fully appreciate the issue with the Readme and will be allocating time to update it. I have been fixing something else and as such have not got around to it yet. I also wanted to do a video to actually explain how it works properly. The reason the documentation is hyped is partly because I wanted to make it appealing, but also to practice my sales copy skills, which seems to have been moderately successful... even if it did defeat the point.

why is the 5xx error page different than 4xx

50x errors are server-related and since most people (me) have DB calls in their standard layout, it was best to use a different layout otherwise it would likely lead to an infinite loop (500 error... show layout... 500 error).

If you replace the nil with application (or whatever your main layout is called), it should start working again...

At present, you'll need to explicitly define each 50x error with the layout you need/want to use:

Sorry for the confusion - this should clear things up.

[kyleduck]

Aye, Richard! Yeah, the "nil" for 5xx started working like five minutes after I sent in the comment. Was probably browser cache or something.

I do a lot of sales copywriting myself, so I get it. Separate discussion but I think gem creators should charge for their work.

Anyway thanks for the gem. Got it rolling in production now. Cheers!

[ckrazycoder]

The Readme really looks like you are trying to sell something :P

[richpeck]

Thanks for the feedback - I just bought RailsHosting.com which is going to be a free way to deploy & manage rails-based VPS servers so I guess it is (in a way). Currently re-doing the Readme to be more practical as well as adding extra functionality.

[jonathanhoskin]

I just wanted to add a +1 to this thread. I was trying to debug a problem with this gem, in an older Rails project that I've just inherited. It's can be time-consuming and frustrating to view a README for a gem and not have it immediately list it's basic usage in plain text. The best kind of promotional advertising for a gem is that it is 1) actively maintained, and 2) appropriately documented.

[richpeck]

Working on a new Readme, thanks for the input.