New homepage and building blocks website

Organisation
, , ,
44

Coming a bit late to the discussion. I’ll add a ‘looks good’ as well. Style is much like ‘readthedocs’ so I quite like it.

Perhaps there could be a link to this guide somewhere on the main menu? a ‘How to contribute’ page? I think having this information on a system that allows controlled modification is a great idea.

But it doesn’t. There is a lot of technical info hidden in resources which is not an intuitive place to look. I’d rather, anything more than a basic setup guide be placed in this learn area.

Ironically, the 2 screenshots are not consistent. Neither is learn v community. Ok so it is in a different format (a pull down menu which in itself is confusing) but the items in the menu are in a different order.

The ‘resources’ section is the worst offender and a link has appeared at the top of the community page directly to it as well, despite it being part of the ‘guide’. Again, the top bar of the guide is different again and you cannot get back to ‘home’ from it. The fact it is now being linked to directly really should tell you something.

All top bars should be the same even if you are in that section so you can get back to the main page of that section. Making the left image a ‘home page’ for that section is counter intuative (to me at least).

Edit: I note you quote Platformio as your inspiration; you should therefore see that wherever you are in the site (and they use ReadTheDocs), the top banner is exactly the same, and the top left is always back to the root domain page.

As the learn site is editable on Github I’d suggest a ‘development’ area at the bottom of Learn where things that are under development can be added - clearly marked as such (and on each page so landing from a search makes it clear). As the discussion / development work continues, the page can be updated by the person with most interest. Once is is stable it could be moved into the main sections. If it dies, it could be removed.

It does look good and is a great improvement :smile:

45

Overall, I think the ‘Guide’ should be folded into this ‘Learn’ structure to provide a coherent journey.

I suspect a lot of people are currently put off as it just looks far more complicated than it is. In all honesty, it does rather look like something that is not for the non-geek (which it isn’t). It has currently fallen into the classic mistake of forgetting that those you are trying to attract do not know what you know. For instance, from the home page I click on ‘Energy Use’. I get dropped straight into something talking about required hardware and setup without any explanation. If I do click on ‘Required Hardware’ (which is under setup), it starts talking about needing a CT sensor. ‘Sorry what is a CT sensor and how does it all fit together?’ Currently a new visitor is dropped into the deep end without a float!

Let me be clear, I think the vast majority of the required information is available but it is not laid out in a way that allows natural progression from ‘I want to monitor Energy Use’, through the ‘What options are there and how will it fit together’ and into the ‘I’m going to buy’ phase and then ‘I need to set it up’ and on to ‘what else can I do with this?’.

I suggest ‘Learn’ should start with an ‘About’ section explaining about the various parts of this ecosystem and help a newcomer to decide what to use (EmonPi, EmonBase, EmonTX, local logging, remote logging etc). This I think is the biggest hole in your whole structure. It is very difficult to understand how all the different parts fit together and the various options available. Many of the links from the home page drop you straight into a ‘setup’ page.

The diagram at the bottom of the main setup page is the best place to start. Consider this scenario; I have a Pi and I am looking for the cheapest way to monitor energy consumption. I have dropped onto your home page. At first glance it is £170 for an EmonPi (including power supplies which for some reason are not included by default and little explanation of the AC adapter requirement). £170 is a lot for most people. However, I actually know, that the Pi Shield (which for some reason is not listed separately on the shop) is available and so for a minimal system that is the way to go and I save myself £100.

So what else can I do with this ecosystem - ah, an excellent piece of software that allows me to record energy usage and much more when integrated with Node-Red, OpenHab etc. Other nodes for temp/Hum/CO2/Relays communicating by RFM, Loightwave OOK etc, etc etc. All this should be in an ‘about’ section that explains the ecosystem to newcomers. It is a great system but you really do not sell it.

‘Learn’ should then have a setup section that, if the user wants to go beyond the standard (such as multiple Temperature sensors), directs them to a section within ‘Learn’ (rather than jumping to a completely different structure). If they just want a bog standard setup then that is a simple step by step.

Learn should then go into the theory, more detail on the technical aspects of the different parts both Hardware and Software and other uses for the ecosystem (Node-Red, OpenHab, Lightwave etc).

I suggested a ‘How to Contribute’ menu item. This should link to the ‘editing on github’ guide and also say how you’d like errors or omissions reported. Do you want to use the issues system on GitHub?

For instance, I notice that the page Learn | OpenEnergyMonitor linked to from Learn | OpenEnergyMonitor does not have a menu entry.

Anyway, just my ramblings…

3 Likes
46

Sorry me again. I went back into ReadTheDocs (I have used it for pywws) and realised that the menu structure for that looks better (and is also GitHub based).

The immediate thing I notice is that the menu on the left has more depth. Is this something you can configure on this implementation?

I can’t see anything about how you are publishing the pages from GitHub. Is it Jekyll again?

Cheers

1 Like
47

Great analysis Brian.

Maybe the way forward is to create a flowchart based on an expanded version of Brain’s questions and then build things up in that way. Not of course showing the flow chart… Just a natural Q and A way into the material.

Interested in energy monitoring? Nothing to work with? Get an emonPi.

Interested in energy monitoring? Got a Pi? Well there are a few ways forward; 1). emonTX and an rfm adapter, 2). etc. Got the hardware, now do you want to just get cracking? Download the SD image. Not interested in OpenHab and OOK etc. then start installing everything from scratch.

etc.

Simon

EDIT - having said that you guys might want to take a break from this for a bit and re-attack it in a couple of months.

2 Likes
48

Hi Brian, It is a dynamic site built from the ground up and hosted on our own server. It pulls in any changes from the GitHub repo automatically (GitHub - glynhudson/Github-Auto-Deploy: a server that allows you to automatically deploy the latest version of your github project at each git push). Adding more depth to the menu would be possible and the styling is easily changed.

You make very good points in your posts. There is more work to be done to improve consistency between the sites and we know there is big room for improvement. An idea would be that the contents of Guide could be migrated to the Learn template we have built. We’ll be changing the Guide to conform soon and it will be a chance to look at the structure of how we’re presenting the information. I like your idea of building from my diagram.

1 Like
49

Thanks for your feedback @borpin, It’s really great to hear constructive and specific feedback. Really appreciate you spending the time.

Yes, a ‘how to contribute’ page using GitHub to edit docs would be a good idea. Is anyone able to help us make one :blush: ? It would be great to have it written from the perspective of someone who doesn’t spend 8hr dealing with Github every day!

Yes, I agree there is a fair bit of technical info currently in the guide. e.g. the technical section. We will be moving the firmware / compiling page from guide to learn.

However, I’m not sure that ‘learn’ is the best place for all the tehnical stuff, since much of it e.g. SSH, MYSQL credentials is very specific to the emonPi setup. IMO the best place for documentatin specific to a certian hardware item e.g. hardware pin map, firmware upload instructions etc is on the github respository for that hardware item that way the documentaion can be version controlled together with hardware and firmware revisions. This is a pattern we have been following with our newer hardware units e.g. emonth2, heatpump monitor and I recently move emonTx V3 defaut firmware to a new repo following this syle: emonth3. So the firmware, hardware CAD design, and tehnical docs for each hardware item will all be in one place and version controlled together.

Totally agree, the top bar needs to be consistant. We’re working on it :slight_smile: . The homepage and community forum top bars are now the same, minus ‘home’ on the home top bar and ‘community’ on the community top bar as it doesnt make sense to link to have a link to the same page the user is already on.

So far the Guide has been neglected while we have been working on Learn and the Homepage, over the coming weeks the Guide will get an overhaul and the common top bar will be added. We’re also looking at adding the common top bar to the shop.

I propose using the labs forum category for dev suff or just the forum in general. I have pinned a post which lists active dev topics copied old forum labs section as a pinned topic to the labs section of the forum.

But will it?! It’s incredibly difficult to review docs and then try and decide if they are worth removing in the fututre. The reality is even if we decide not to continue development of certian item this does not mean that bit of development should be deleated. It could still be useful for someone to build upon in the future. The great thing about using the forum (and dedicated github repos) is that older neglected topics and repositories naturally sink to the bottom old the be re-surfaced in a search. Btw have you noticed how amazing the new forum is for searching and finding old topics? Much improvment over the old Drupal forum.

We really want to try and improve the experiance for a new non-technical user. This is the reason we created the Guide. Do you not think that learn would be even more overwhelming for a new user? A new user does not need to be dropped into AC theory and CT burden resistor calculation. The idea with the guide was to present the minimum information the user needs to choose, install, setup and use a basic system. There is definitely scope for improvement, thanks for noting that a ‘CT’ is not explained well enough. I will look at improving this.

We built the first page of the Guide to try and give an overview of each hardware item with comparison table etc. What do you think of the three section of this page explaining the hardware required for each type of system and what each hardware does: System Overview — OpenEnergyMonitor 0.0.1 documentation. Maybe the URL ‘setup’ is slightly misleading, we could rename it to ‘about’?

Yes, github issues are great :thumbsup:

Thanks again for your feedback, we’re all working hard to improve the site onwards and upwards!

If anyone would like to help: Learn, Guide and the new Homepage are all fully open source on GitHub:

1 Like
50

I have to disagree. Look at PlatformIO. It is exactly the same wherever you are. Perfect in my mind :smile:

1 Like
51

But can you not simply pull that information into the ‘Learn’ structure so it is all in one place even if the source is somewhere else? The problem is indexing what you have so users are aware of it. So much of the information is interlinked and jumping about through different sites is far more confusing. Also, the reading of documentation directly on GitHub is a far less relaxing occupation.

No I don’t. I think a new visitor to the site is likely to be overwhelmed by being dropped straight into something that talks about setup on the page they are reading. Seeing it (setup) as a separate menu item, which clearly part of a more extensive documentation pack, is likely to be comforting. An ‘About’ page should explain the ecosystem, helping them understand how it all fits together, so they can make an informed decision about what to buy and how to install/use it. Personally, I tend to look at the setup / install before I buy so I am confident I am spending money wisely (but that might just be me). I also do not think this has ever really improved. I remember being totally confused by EmonCMS and EmonBase when I first looked at this years ago!

I do think the jumping between different ‘sites’ should be minimised.

YMMV

52

That is smart. Can it pull from different repos into a unified structure? That would provide an easy way to combine the documentation from the different hardware based repos into the single documentation environment.

You should add a page in explaining how it works :smile:

53

Just to clarify @borpin are you proposing that guide is a section in Learn: i.e there would then be Guide, Electricity Monitoring, Sustainable Energy, PV Diversion?

Or that Guide is integrated in the Electricity Monitoring section, or that Guide is just transferred from the Jekyll based theme to look exactly the same as the Learn template?

Another benefit of using a github repo for Learn is that you can download the whole site yourself and host on your own local server on your computer for offline access :slight_smile: if you have apache2 its a really easy git clone or download and unzip to install.

1 Like
54

I think you’re right that we need to revisit the home energy monitor and solar pv guide as they are missing some crucial introductory information when you click straight in from the home page.

1 Like
55

I think the information in the guide needs to be folded into the ‘Learn’ environment but not just dropped in. As it stands, the structure of ‘Learn’ is not right. You have temperature measuring under Electricity monitoring for instance. Time Series (which was really interesting BTW) is not just about electricity monitoring and neither is EmonCMS.

How about (and a real starter for ten - might need a new thread - not complete by any means);

  • About (Start Here)
  • How it all fits together
  • Common Uses
    • Energy Monitoring
    • PV Monitoring & Diversion
  • Different options
  • Setup / Install
    • Basic EmonPi Setup
    • Other Sensors
  • OEM Hardware
    • EmonTX
    • Networking and MQTT
    • EmonHub
    • Editing Firmware
  • Other Sensors
    • Relays
    • Plug in monitors
    • Temperature
    • Gas
    • Water
  • Software
  • EmonCMS
    • EmonCMS Internals
    • Timeseries
    • API
  • Node-Red
  • OpenHab
  • Electricity Monitoring Theory
  • Sustainable Energy

As you can see, this is largely the information currently available, just structured in such a way as to provide a journey.

There are questions such as would information about self installing EmonCMS go under ‘setup / install’ or software but that is small beer IMHO.

It is like an index to a book. If you only had the chapter titles and had to go to another book just to see what the chapter contained, you’d get hacked off. With everything in one place, all you need to do is explore the menu and you will probably find what you need.

HTH

56

Thanks @borpin, we will keep working and thinking on this, its going to take some time to get it all right and its probably worth mulling all of it over for a bit first. Where would you put these pages in your structure:

https://learn.openenergymonitor.org/electricity-monitoring/ct-sensors/interface-with-arduino
https://learn.openenergymonitor.org/electricity-monitoring/ctac/how-to-build-an-arduino-energy-monitor

Do they go under:

  • Electricity Monitoring Theory
    • AC Power Theory
      • Introduction
      • Arduino Math
      • …
    • CT Sensors
      • Introduction
      • Installation
      • Interfacing with an Arduino
      • …
    • Voltage Sensing
      • …
    • Current & Voltage
      • …

With much the same content as is presently in these subcategories?

57

I’d say the theory behind CT sensors goes in the theory, but actually using them under setup as they are pretty fundamental to setting a system up especially with the associated warnings. I think though, the installation probably goes further than needed for someone who just needs to clip it on the right wire! Some of the information in ‘Install’ is more akin to the ‘Introduction’ page and some of the Introduction page drifts into Installation and theory which the normal bod is not really interested in!

The interfacing with Arduino could go under a hardware or sensor page. I’d also put links like ‘If you want more information on how a CT Sensor works click here’… which then points to the theory & if you’d like to use a CT with an Arduino click here. Browsing through the menu will reveal the relevant pages as will a search.

The key questions I pose myself when working out where I’d put things are;

  • Is this needed to help explain how everything fits together in a non-technical way? (about)
  • Is this needed by most people in setting up a system? (setup / install)
  • Is this information going to be used by an advanced user? (Hardware & Firmware / Software)
  • Is this simply explaining the theory behind why something is how it is. (Theory)

An example of the latter is the work you did on minimising then measuring battery life. Explains why you have done it the way you have.

Another example springs to mind “why would I want an AC adapter”. It needs a simple pro/con explanation in About (to inform the purchase), a little bit in install (as it impacts the CT sensors I think) and a whole chunk in the theory part I’d suggest. For me, I only am interested in the question should I buy it and then how do I install it. Many others will be interested in the theory :smile:

You can then link from the shop - next to the AC selection, to the About page.

Sounds good in theory…

1 Like
58

That runs counter to one of the points Brian made a bit earlier in this thread.
That being it does rather look like something that is not for the non-geek (which it isn’t).

Which brings the question “Isn’t the example of running an Apache server just a bit on the complicated side for the average user, let alone a new user?”

Those well-versed, or at least comfortable with Linux or IT in general, won’t have any problems with setting up something like that. But they are a bit less likely to need such a reference.

The new user, (and I suspect the majority of users) isn’t going to have such a setup.

Those involved in IT, Electronics or other high-tech jobs, might already have their own servers or not have an issue with setting one up. But for the user who just wants to monitor their energy use, it sure seems like “overkill” to me.

Brian goes on to say:
It has currently fallen into the classic mistake of forgetting that those you are trying to attract do not know what you know.

I’ve said the same thing. While there may be no Linux trickery involved, the average person probably doesn’t have much of a clue about things like SSH, Git, scripts, Python, etc. let alone things like CTs and common electrical terminology.

Bottom line?
Ensure the explanation in the Learn section (or where appropriate) is one Joe Lunchbox can comprehend.

Brian is right, (and I’ve heard Robert say essentially the same thing) we’ve been doing this for so long, it’s second nature. It’s easy to lose sight of what it was like when we were just starting out. High-tech stuff isn’t everyone’s bailiwick.

59

In @TrystanLea defence, I think he was aiming the idea at me rather than suggesting this went in the Joe Lunchbox section.

Would fit quite nicely in a page about the documentation and how to contribute.

Thanks for the kind words :smile: Good documentation is not easy.

1 Like
60

And that’s OK.
But you sum it up nicely here:

Which is to say that many users are just that, users.
They aren’t interested in how it works, they just want it to work.

61

@borpin Brian, you’ve managed to elucidate a lot of the points that I’ve struggled with for a long time. I think the key problem is that OEM had grown organically over time and …

Yes, but there comes a time when old stuff simply has to go. Or be incorporated into current data & practice. There’s nothing to stop you from marking the material “Obsolete” or something like that as a warning that it is superseded/not supported/not in development or whatever.

Having contributed a fair slice to Building Blocks, I’m only too well aware that there’s a lot of duplication in there. This is where a critical review based on “what would we have, knowing what we know now, if we were starting from nothing” should take place and only when that overall strategy been decided should you look at the old material to decide what is usable for incorporation.

But it does if it’s greyed out - it serves as a signpost to let you know where you are. Sorry Brian, but I hate menus that reload the page I’m on. [F5] does that if I need it.

I concur. When I was putting together a website for my friend’s B&B business, I spent quite a bit of time reading up about page layout and where to place things, and the point that everyone hammered home was “you’re only ever one click away from losing a customer”. Everybody involved here needs to step back and look at the site from an ignorant newcomer’s viewpoint. And make sure that new customer doesn’t click away for all the reasons everybody has mentioned.

That’s what I mean by ‘what is usable for incorporation’. They’re good pages. Students etc still use them and build projects with them. But they must not be shoehorned into a structure just because the structure is there. If ‘Learn’ is about Megni-supplied kit and OEM software, those pages should NOT be there. I think I’m with Trystan here - those pages demonstrate the theory, so that’s where they go (but maybe rewritten to incorporate the material better into the theory rather than transplanting them wholesale). Like a lot of the material here, there’s a lot of crossover, and that’s the source of many of the problems that are surfacing in this discussion.

That’s the biggest understatement of the year (so far). It’s not ‘not easy’, it’s very, very hard. And time-consuming. And not often appreciated. And definitely not cool.
But done properly, it’ll cut a slice off the support effort that goes into the forum.

3 Likes
62

Yes, this is exactly how ‘learn’ works, parts of learn e.g. zero carbon energy model come directly from a separate zcem github repo.

Ok, you have convinced me. We will aim to have an identical common top bar between all sites with the site the user is currently visiting highlighted to indicate user location. This is a nice idea. Looking again, this is how the platformio top bar works.

1 Like
63

Agreed and I was not suggesting that, but just keep the top menu consistent across all the different parts. If it is, you always have a way back to the domain home page and also to the top/home page of the part you are on. I don’t mind it being like the forum, that hides this as you scroll; I know it is there if I want it.

It is a jigsaw; all the bits will fit together to make a great picture but it takes time to arrange them and fit them in where they should go.

I’m not so hot on the actual technical stuff, but I can spot inconsistencies or potential gaps and also provide a perspective on where different parts could go so happy to help.

1 Like