Community
OpenEnergyMonitor

Community

First Aid for Emoncms


(Brian Orpin) #1

Continuing the discussion from Error after upgrading:

[Updated 1/12/18]

Might I suggest a pinned post for the community that is a ‘First Aid if Emoncms doesn’t Work’ - possibly include how to add the admin information to any request for help.

First Aid for EmonCMS; Please try these steps before you ask:

  • Check in private or incognito window and if problem disappears - clear cache
  • Update database
  • Update modules
  • Enable SSH :smile:
  • Set log level to INFO by editing settings.php [added 1/12/18]

What else?


(Paul Reed) #2

Nice idea Brian.
Many of these issues are duplicated, so would be good to work through a checklist.


(Bill Thomson) #3

Add it to the FAQ section?


(Trystan Lea) #4

Yes, good idea and to add to the FAQ section. I will put a list together and add to your efforts.


(Brian Orpin) #5

Yes and no. The FAQ is quite hard to navigate, might benefit from having each answer as a details. I think there is a benefit to a pinned post for those arriving for the first time. I do tend to read pinned posts on Discourse forums!

But adding it to the FAQ is better than nothing.


(Paul Reed) #6

A pinned post may be the best option (which of course can be user ‘unpinned’)
Also encourage users to bookmark the thread, so that they can easily return to it if they have problems.

Please bookmark this for future reference -
image


(Trystan Lea) #7

I’ve added a clearer link to The FAQ in the welcome page and added FAQ to the title to avoid a large number of sticky threads. Does that help do you think? or a little confusing to have to click through to a second page?


(Bill Thomson) #8

I’m curious as to what it is that makes the FAQ hard to navigate.
Brian is the only person (that I can recall) who has commented on the FAQ being hard to use.


(Gwilym Noble) #9

I don’t think it’s hard to navigate - there’s just a lot of info there; but we could improve the presentation. Back when I suggested moving the FAQ, I did experiment with making the answers collapsible - I think it works well.


(Greebo) #10

FWIW, I just had a quick look at the FAQ and I can see what @borpin means.

There’s really only a single “section” and it is titled How to ask for help
A number of the items later in the list actually provide help, so perhaps there should be a second section heading Solutions to common problems (or something like that) above those solutions?

Collapsing all of the answers so that the questions are easier to scan through might also assist.

Putting my “lazy Internet user” hat on, I read that first heading and then just scanned through the list looking for the next section as I wasn’t there trying to find out how to ask for help

There’s a reason TL;DR is a “thing” unfortunately.


(Brian Orpin) #11

Navigate in the sense of picking out the wood from the trees.

That’s because no one reads it :smile:. …

That was my first time and it took me a while to notice where it was…

Check the stats, how often is it read and for how long?


(Bill Thomson) #12

Hi Greebo,

It wasn’t really intended to be a section heading, but rather something to catch a user’s attention.

Questions get asked, but very little info is given to us to go on. When that happens, we end up going
several rounds back-and-forth just to gather enough info to be able to help the user resolve their issue.

I made the text large and bold in the hopes it wouldn’t be missed.

Why not use the forum search function? (another one of those things not read and/or used)
If a user actually used the search function from the main forum vice the FAQ page, there’s
a reasonable chance they’d find what they’re looking for, or at least something close enough
that it may still be of some help. I’ve read every post on the forum, and have seen this many times.
e.g. users will ask a question that’s not OEM specific, i.e. a general Linux inquiry. If they searched for it
with whatever search engine they like to use, they’d have found the answer.
(When the forum software was switched from Druplal to Discourse, I started reading all of the posts made
every day. I haven’t stopped. Next April will make three years)

I’m not bragging. Here’s the stats:

As you can see, there’s only a few folks who are familiar with the bulk of the forum “contents”
because they’ve read all or most of the posts.

It’s obvious this forum is being carried by two people, and I’m sure as hell not one of them.
Chaps, my hat’s off to both of you. thumbsup

Which proves the point Jeff Atwood (co-creator of Discourse) made when he said help and/or FAQ
buttons on a bav bar are useless / worthless.

That’s a good question. I’m sure there’s a way to do that, but I don’t know what it is.


(Greebo) #13

I’m with you 100%, however as anyone who has gone Googling or Binging for something they don’t yet understand would know, the challenge is when you don’t know what search terms to use. Usually once you know the answer, you know what the right search terms would have been to put into the search to find said answer, at which point its a bit late! In my experience, the same applies in spades on this forum.

My post was actually a reply to:

It wasn’t trying to solve the “how do you help people to help themselves” problem. :smiley:

+1 from me on that!


(Bill Thomson) #14

I’ve found that even if one doesn’t know the correct terminology, Google’s “fuzzy logic” works pretty
good and quite often is able to figure out what’s bieng asked. It’s improved steadily over the last
few years, and while there’s no substitute for the real deal, it’s surprising how well it works.

No worries, just explaining why I did what I did with the text. :wink:

But… The point is a valid one. I’ll change it so it doesn’t look like a section title.


(Brian Orpin) #15

That was where I started with this - as it stands I don’t think the FAQ quite solves this problem hence the suggestion of a First Aid pinned post for users to try (be pointed to) when first asking a question. The How to Ask For Help is OK, but it really needs a Try these steps before you ask section (which is the idea of the First Aid).

Yes completely agree.

Perhaps the structure should be (and this can be setup in discourse to pop up when crafting a question I think);

  • Not working? Try these steps
  • Still not working? Try common problems below and searching the community
  • Really stuck? Ok so this is what we will need to know to help you

As said elsewhere, that is fine if you understand what question/answer you are actually looking for.


(Gwilym Noble) #16

Yes, this is easily done. Currently this is set to the following:

Welcome to the OpenEnergyMonitor community — thank you for contributing!

Does your reply improve the conversation in some way?

Remember to always be respectful. See our code of conduct.

Please DO NOT link to images hosted on 3rd party sites!

If the site your images are linked to becomes unavailable, your post loses its value.
To prevent that from happening, upload your photos directly to the forum -
i.e., attach them to your post.

As a new user, you may upload 3 images. Please ask if you need to upload more.


(Jason Crawford) #17

I’d like to suggest a first aid page/section for “my feeds have stopped updating”. Searching the forum doesn’t turn up a good clear recipe for diagnosing this. Unless I’m looking in the wrong place, the FAQ doesn’t seem to address this. But this is the problem that keeps on sending me back to the this community looking for answers. (And that’s why I’m here today.) Also… attempting to create a recipe might actually help the contributors that answer questions… and debug/fix the code.


(Jason Crawford) #18

BTW… to be fair, and to finally contribute, I’ll offer to help, but my help probably would be limited to pointing out where I or someone else ran out of recipe and now need more help.


(Robert Wall) #19

And believe it or not, that is quite valuable help for the helpers.


(Brian Orpin) #20

I looked at that. The problem is unlikely to be a common one, but setting logs to INFO is a good first aid step.

It is the people who are not familiar with the system that can most easily point out faults and omissions to documentation as they explore and learn.