@Gwil@glyn.hudson and I have been quietly working in the background for sometime on a website overhaul for OpenEnergyMonitor including a new landing front page and new site called https://learn.openenergymonitor.org.
The idea behind learn.openenergymonitor is to bring all of the work on Building Blocks, Understanding Energy and PV diversion more to the fore of the project and to make these resources easier to navigate.
The sites are designed from the ground up to work with a variety of screen sizes including mobile and tablets.
We are not far off being able to go live with this, thereās a little more work to do double checking links and completing the dropdown menu on the front page. We would be interested to hear what you think of it and whether you can spot anything that needs fixing/adjusting?
I have attached a number of screenshots below of what it should look like in case there is any display issues that we have missed on different browsers, so if you dont think it looks quite right, please look at these first.
Old Dupal site
āLearnā and the new front page website would replace the current use of drupal. With only the old forums being kept as an archive. We would delete all the other content that has been moved over to learn in order to avoid confusion.
Learn is a repository on github and anyone can propose a change by clicking on the āEditā button on any page which directs to the learn github repository edit page:
Changes are publicly transparent (as pull requests) but have to be approved by a repository maintainers currently (@glyn.hudson and I). We can add the @moderators if they like also as repository maintainers so changes can be approved quickly. Please let us know if you would like to help out as a repository maintainer.
When viewed on a mobile device the menu colapses and can be brought up by tapping the āburger menuā. All pages have been designed to work well on mobile devices and small screens
This is becoming really a nice layout, all nicely integrated. Also the colours are slowly converging.
Time to wave goodbye to Drupal that served well but is a bit outdated now.
No problem helping out in the backoffice though Iām not yet used to Githubās internals (never to late to learn) though I think we (moderators) need to know where not to go. My knowledge isnāt big enough to statue on electrical matters going further then the basics, but maybe we can invent some escalating system with several levels with other moderators.
Something like level 1 (me for ex) reading as first what comesin, if I can handle I do, if it is going above my knowledge, I escalate to level 2 where more skilled people can handle and then to level x where Glyn, Tristant and Gwil take care of what canāt be done by us. Not to many levels though but at least those with best knowledge (and most probably needing most time to check) can concentrate on changes that need in-depth control.
Iāve had a quick look at https://learn.openenergymonitor.org/ and two initial comments: (1) I like the look and (2) letās do a thorough job and carefully review everything before it goes public. There are some holes and a lot of duplication in the old Building Blocks and, while I donāt think there are many instances where it is contradictory, a serious editing effort is called for. (e.g. thereās no mention of using "scales = " in emonHub for calibration, nor anything specifically about calibration and the emonPi.)
Is learn going to be THE place for all documentation? I sincerely hope so, and if it is, can there be some guidelines and framework established so that thereās a structure, and those who contribute will be able to write knowing how it will fit in with the overall scheme and objectives?
An important practical plea: I believe itās vitally important that all the information is brought together into a cohesive whole. Based on what I read in the Forums, the present scatter-gun approach where information is in 3 or 4 places is a major stumbling block for newcomers - and some not so new too. I see it is the intention that, as soon as something appears in learn, it will be removed from BB, the Wiki, GitHub or wherever. Can we please make sure that is done not only for material that is copied, but also for material that is duplicated, and can we please, please clearly mark outdated and/or obsolete material as such so that people canāt mistake it for current practice?
No, please immediately replace moved or deleted content - wherever it was - by a page that explains that itās moved and gives the new source and a link. I donāt think a link or a redirect alone is good enough, we need to show people that the old is swept away and itās now all in one place.
Iām with @bidouilleur in his ignorance of GitHub - so far, Iāve found it impenetrable, probably because Iāve never had the time to read any documentation about it more than once. So its use is a serious retrograde step from my point of view.
Itās good that overall control of the layout and content will be kept within a very small circle of administrators and that all submissions and changes are reviewed by them for accuracy and applicability.
Learn will replace Building Blocks, learn will contain first principal general info e.g what is AC power?, how do CTās work?
The user guide will contain user setup instructions
The Wiki and GitHub will contain technical user documentation.
Yup, totally agree. Building Blocks will be removed (with a URL re-direct to lean) once learn goes live.
Github is a powerful tool, I donāt pretend to understand or use all of its functions. However, at the simplest level using github will give us revision control for documentation, this is very useful. To be able to edit markdown on github no knowledge or command line is needed just click the pencil icon and edit away, just like on druapal editor. See edit on github guide. Using github has the advantage that anyone can ācloneā the ālearnā repository and work on the entire site offline.
How will newcomers, who arenāt clear about the distinction between these various concepts, know where to look? Maybe more to the point, how will they know that there are 4 totally distinct places to look?
If youāre intent on keeping all 4 locations, methinks we need an overall contents/index to all four āvolumesā.
So for a start, Calibration Theory can stay in learn, but the Calibration Procedure as part of the setup instructions needs to move into User Guide? These are the sort of inconsistencies that the Supervising Editor needs to be on the lookout for and to sort out.
@Robert.Wall yes your quite right that there are certain parts of Learn that blur the lines between the user guide and a more general learning resource, calibration being a good example especially in the way it is written. It is perhaps in this case the calibration procedure for any monitor built using the current emontx2/3, emonpi input circuitry and EmonLib. It could also be used by someone building their own breadboard energy monitor such as: How to build an Arduino energy monitor. The editing guidelines should reflect this and our efforts to edit and prepare learn before being published.
We see learn as being the space for a more general learning resource in the present 3 domains of Electricity Monitoring, Sustainable Energy and PV Diversion. These may not be specific to OpenEnergyMonitor products/hardware units. While the guide is very much: This is how to setup the emonpi, configure inputs in emoncms etc.
Github and Wiki documentation
We have been moving over to having a github repository for particular hardware units (and significant versions):
The idea moving forward is to include both the firmware and the hardware files for a particular piece of hardware in its own repository, rather than the original approach of having a github repository for all Hardware and a github repository for many revisions of the emonTx. We are also keen to try moving new technical documentation that would have otherwise been placed in the wiki to a particular hardware units github repository
Building Blocks Redirect?
I appreciate that a redirect without a notice as to why the redirect has taken place could be confusing. We could detect that the user has landed on Learn from a redirect and display a notice to say āYou have been redirected from the old building blocks to learn.openenergymonitor - the new location for building blocks documentationā. We could also detect the redirected URL and map the redirect across to the specific page. @Robert.Wall do you think this would be sufficient?
I donāt know. All I am conscious of is the number of comments in the forum that say in one form or another: āHelp, Iām totally confused. Tell me what I need.ā and the number of times @pb66 (notably, there are others) has to repeat more or less the same advice over and over again because itās too hard to find.
Iād be quite happy to write a generic calibration procedure for learn and a specific one for OEM products.
For redirects Iād say direct with no page for 2 reasons
ranking can be completely lost (not that ranking is essential, but if a robot shows wrong links ā¦ detects it, they get deleted ā¦ weād lose search results)
people tend not to click 2 times for the same thing, it aināt there, they go back and try another link from the search results ā¦
Plus the fact you can āinterceptā it and show a little nice pop up like, āyep it all changed a bit, please bookmark the new pageā ā¦ or something like that.
thatās regarding that part
Regarding the scattered info, got to say true but I guess this is often an intermediate period when things āgrowā. Many things are added, things change and as you donāt always have a clear view from the beginning where it all goes ā¦ you try several things and end up a bit like it is now.
Not sure there is a āreal and uniqueā solution. Guess the several systems add their value and not one single covers all (remember Iām not the expert here )
So maybe letās try to see this the traditional way. We want to sell (information) and our customer (the surfer) wants to find easily and quickly what heās looking for (immediate satisfaction generation).
If we take this as a general lead, what solution would be best ? Can the different systems be interlinked, embedded in each other maybe so it looks like 1 solution to the surfer and only back office is divided in modules ?
Just a thought . Think those who āmasterā the tools best will be those who can give the best answers ā¦ and I donāt master the tools ā¦
That is exactly why I suggested [quote=āRobert.Wall, post:6, topic:2746ā]
we need an overall contents/index to all four āvolumesā.
[/quote]
so that everybody needs only to search in one place.
Thankyou @Robert.Wall that would be much appreciated and a kind offer, Im happy to enter any changes in github if you would prefer to send a word document with edits.
Do you mean direct map to learn page replacement or to learn home with a notice?
I think there is value in having distinct sections. For example, itās quite common when you buy a new product to have included in the box a āQuick Start User Guideā and also a āTechnical Manualā.
Since we donāt include any paper based quick-start guide in the box I see the User Guide site as being the equivalent: a non-technical (where possible) step-by-step guide to getting users up and running using the basic system in default configuration without overloading them with technical info.
Where appropriate the User Guide will link out to technical info in ālearnā and the wiki/Github. We will also be maintaining the Resources section containing a definitive list to all the resources for each hardware item.
I agree, all sites should look very similar and be a smooth transition, we (or rather @Gwil) have been working on a common top-bar scheme that will be rolled out to all the sites (including the forum and shop) when itās finished:
Reading through the networking section im aware it needs updating.
At the moment we have the following pages:
Which radio module - useful guide written by @Robert.Wall on identifying different radio modules used with OpenEnergyMonitor kit over the years. Perhaps more user guide > Technical section, rather than learn?
Rfm12b wireless - Technical spec for RFM12b and notes on connecting to an arduino suitable for Learn type content.
Rfm12b2 - RFM12 & 69 firmware use/modification guide - useful for either understanding or modifying OEM kit or using to integrate the RFM radioās in self-built kit.
Wifi - old guide on using the Edimax adapter, content is pre emoncms wifi module and integrated support in emonSD image.
Iāve removed the much older pages currently on building blocks including: XBEE, ASK RF link, Arduino Master/slave simple serial networking
I think this section needs a networking introduction page explaining the variety of networking options available RFM12/69, ESP8266 Wifi, RaspberryPI Ethernet/WIFI (external/USB) to name a few. Including a brief mention of the use of these technologies in OpenEnergyMonitor units.
Perhaps the rfm12b and rfm69cw technical info could be moved to this introduction with the parts on identifying the modules removes as this is duplication of the āWhich radio moduleā page.
A brief overview of RaspberryPI Wifi options in the introduction could replace a dedicated wifi page. There are probably better places and online guides available rather than having our own page here.
If we moved āWhich radio moduleā to Guide > Technical and replaced the other pages with a networking introduction/overview that would however only leave one leave two pages in the networking section: Introduction and RFM12/69 Firmware Guide
As part of the bigger change outlined above, Iāve been working on making this forumās look and feel match that of the new theme. If anybody has any suggestions or notices an error, sluggishness or bugs (particularly on various devices, screen sizes, browsers, etc.) please let us know. Things are likely to change over time as the rest of the project develops.
I think these are candidates for comprehensive revision.
Quite a few users want to use serial to connect into the Hub. Not strictly networking, but it must not be forgotten - itās ānetworkā if not āInternet/Intranetā
Thanks @Robert.Wall I havenāt unfortunately been able to progress this this week, but yes agreed and good point about a need for a guide for direct serial connectivity.
and I have removed the WIFI page for reasons given above, there are better resources/guides elsewhere for RaspberryPi + WIFI connectivity and the software configuration for this has been included as standard in the emonSD raspberrypi image for some time.
I was trying to find the old guides on PV diversion and expected them to be linked through the Solar PV section of the new format - sadly they arenāt. Can you include these?
Also on that main page, you have to click on ālearn moreā below the headlines for the contents of each section and you canāt click on the image/graphics above. Can you make those images into clickable areas so that itās easy to get to the info that way.
Also, the ālearn moresā are slightly confusing to the eye as they almost appear to be under the next column, so maybe this needs a bit more formatting to make them obviously part of the headline list above them - if you see what I mean
Simon
PS Great work so far - itās a PITA doing this but it really makes things a lot easier for both new and old folks. Thanks.
Thanks @Bramco, the PV Diversion guides are available here: Learn | OpenEnergyMonitor and are one of the three main Learn sections. Perhaps there needs to be a link through from the SolarPV guide too?
We will have a look at the learn links on the main page to see if we can improve, thanks.
. Think those who āmasterā the tools best will be those who can give the best answers ā¦ and I donāt master the tools ā¦
