New homepage and building blocks website

[glyn.hudson]

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

@borpin

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.

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

@borpin

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.

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.

@borpin

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).

Totally agree, the top bar needs to be consistant. We’re working on it . 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.

@borpin

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.

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.

@borpin

If it dies, it could be removed

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.

---

@borpin

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!

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.

@borpin

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?’.

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’?

@borpin

Do you want to use the issues system on GitHub?

Yes, github issues are great

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:

GitHub - openenergymonitor/learn: OpenEnergyMonitor learning resources...

GitHub - openenergymonitor/guide: OpenEnergyMonitor User Guide

GitHub - openenergymonitor/homepage: OpenEnergyMonitor front landing page