Topics

Reconciling hardware help pages #WebHelpUpdate


JerryG
 

As part of my on-going review of /help/en/, I'm now trying to reconcile the names of hardware help pages.  They appear (or don't appear) in the sidebar that appears on many help pages (by "including" /help/en/parts/SidebarSupportedHardware.shtml), in the Help TOC, in the Help Index, and on the page /help/en/html/hardware/index.shtml.   Some anomalies are easy to fix (inverting two words, misspelling, different abbreviations - all of which could be confusing to users).  Others are a case of some hardware not appearing in all four places (there are 7 items that appear in the sidebar but not in the TOC, 2 that appear in the TOC but no where else, 3 that don't appear on the hardware index page, etc.).  A couple of situations where I would appreciate input:

(1) Placeholder page https://www.jmri.org/help/en/html/hardware/anyma/index.shtml is referenced in the TOC, but not anywhere else.  Is DMX something JMRI supports?  Should I leave this page, delete, include in all appropriate places?

(2) Help page https://www.jmri.org/help/en/html/hardware/dcc4pc/index.shtml is referenced on the hardware/index.shtml but no where else.  Should I include it in all appropriate places?

(3) The overall list of supported hardware is quite long (47 items already referenced, and possibly a dozen more manufacturers or hardware should be listed) so I would like to categorize them as a way of making lists easier to navigate.  Here is my proposed categorization:
Multi-purpose:
  Example: Digitrax, Arduinos
Networks and protocols:
  Example: CAN Bus, MERG CBUS, OpenLCC, Digi XBee, LocoNet, Modbus, MQTT, C/MRI
Command Stations:
  Example: SPROG, ESU ECoS, MRC, DCC++
Accessory devices:
  Example: DCC Specialties, OakTree Systems, Arduinos
I am not familiar with all 47 hardware items so will no doubt need some interpretation on where things go, but how does this categorization sound so far?  I'm happy to provide my list so far to anyone who wants to take a go at it.

Thanks, Jerry


Andrew Crosland
 

I would like to see a Programmer category for SPROG, as well as it appearing in Command Stations.

If help pages exist for them, then things like Digitrax PR-1 and PR-3 could be added to this category.

Andrew

------ Original Message ------
From: "JerryG via groups.io" <jerryg2003@...>
Sent: 23/04/2020 18:26:03
Subject: [jmri-developers] Reconciling hardware help pages #WebHelpUpdate

As part of my on-going review of /help/en/, I'm now trying to reconcile the names of hardware help pages.  They appear (or don't appear) in the sidebar that appears on many help pages (by "including" /help/en/parts/SidebarSupportedHardware.shtml), in the Help TOC, in the Help Index, and on the page /help/en/html/hardware/index.shtml.   Some anomalies are easy to fix (inverting two words, misspelling, different abbreviations - all of which could be confusing to users).  Others are a case of some hardware not appearing in all four places (there are 7 items that appear in the sidebar but not in the TOC, 2 that appear in the TOC but no where else, 3 that don't appear on the hardware index page, etc.).  A couple of situations where I would appreciate input:

(1) Placeholder page https://www.jmri.org/help/en/html/hardware/anyma/index.shtml is referenced in the TOC, but not anywhere else.  Is DMX something JMRI supports?  Should I leave this page, delete, include in all appropriate places?

(2) Help page https://www.jmri.org/help/en/html/hardware/dcc4pc/index.shtml is referenced on the hardware/index.shtml but no where else.  Should I include it in all appropriate places?

(3) The overall list of supported hardware is quite long (47 items already referenced, and possibly a dozen more manufacturers or hardware should be listed) so I would like to categorize them as a way of making lists easier to navigate.  Here is my proposed categorization:
Multi-purpose:
  Example: Digitrax, Arduinos
Networks and protocols:
  Example: CAN Bus, MERG CBUS, OpenLCC, Digi XBee, LocoNet, Modbus, MQTT, C/MRI
Command Stations:
  Example: SPROG, ESU ECoS, MRC, DCC++
Accessory devices:
  Example: DCC Specialties, OakTree Systems, Arduinos
I am not familiar with all 47 hardware items so will no doubt need some interpretation on where things go, but how does this categorization sound so far?  I'm happy to provide my list so far to anyone who wants to take a go at it.

Thanks, Jerry

--
Andrew Crosland


Randall Wood <rhwood@...>
 

I wouldn’t categorize hardware simply because that can get complex (where does a PR-4 belong? Is it a programmer or a bridge?). How is a user to find a device if they don’t understand or know the category terms selected? Where does hardware that works with JMRI but needs no special configuration in JMRI belong?

The other possibility is that we don’t list hardware on a sidebar, but just have a page listing compatible hardware.


On Apr 23, 2020, at 13:41, Andrew Crosland <andrew@...> wrote:


I would like to see a Programmer category for SPROG, as well as it appearing in Command Stations.

If help pages exist for them, then things like Digitrax PR-1 and PR-3 could be added to this category.

Andrew

------ Original Message ------
From: "JerryG via groups.io" <jerryg2003@...>
Sent: 23/04/2020 18:26:03
Subject: [jmri-developers] Reconciling hardware help pages #WebHelpUpdate

As part of my on-going review of /help/en/, I'm now trying to reconcile the names of hardware help pages.  They appear (or don't appear) in the sidebar that appears on many help pages (by "including" /help/en/parts/SidebarSupportedHardware.shtml), in the Help TOC, in the Help Index, and on the page /help/en/html/hardware/index.shtml.   Some anomalies are easy to fix (inverting two words, misspelling, different abbreviations - all of which could be confusing to users).  Others are a case of some hardware not appearing in all four places (there are 7 items that appear in the sidebar but not in the TOC, 2 that appear in the TOC but no where else, 3 that don't appear on the hardware index page, etc.).  A couple of situations where I would appreciate input:

(1) Placeholder page https://www.jmri.org/help/en/html/hardware/anyma/index.shtml is referenced in the TOC, but not anywhere else.  Is DMX something JMRI supports?  Should I leave this page, delete, include in all appropriate places?

(2) Help page https://www.jmri.org/help/en/html/hardware/dcc4pc/index.shtml is referenced on the hardware/index.shtml but no where else.  Should I include it in all appropriate places?

(3) The overall list of supported hardware is quite long (47 items already referenced, and possibly a dozen more manufacturers or hardware should be listed) so I would like to categorize them as a way of making lists easier to navigate.  Here is my proposed categorization:
Multi-purpose:
  Example: Digitrax, Arduinos
Networks and protocols:
  Example: CAN Bus, MERG CBUS, OpenLCC, Digi XBee, LocoNet, Modbus, MQTT, C/MRI
Command Stations:
  Example: SPROG, ESU ECoS, MRC, DCC++
Accessory devices:
  Example: DCC Specialties, OakTree Systems, Arduinos
I am not familiar with all 47 hardware items so will no doubt need some interpretation on where things go, but how does this categorization sound so far?  I'm happy to provide my list so far to anyone who wants to take a go at it.

Thanks, Jerry

--
Andrew Crosland


Bob Jacobsen
 

It’s OK for things to appear on more than one page and more than one category to point to a page. There’s a reason it’s call the _web_.

How about categories for

- Vendors - Digitrax, Lenz, ..
- Hardware - Arduino
- Protocols and networks and families (probably needs a better name, but basically piles o’ stuff that work together: LocoNet items, XPressNet items, etc.

The original hardware page grew out of adding stuff in alpha order. But some of the pages pointed to started out vendorish and became broader (Lenz -> XPRessNet -> Multivendor), some went the other way (LocoNet got dominated by lots of Digitrax products) So there’s probably interest in lots.

For many people, search is their friend. They’ll put some words they know in the search box and find a page. So having lots of different labels to a page is OK.

Bob

On Apr 23, 2020, at 10:26 AM, JerryG via groups.io <jerryg2003=aol.com@groups.io> wrote:

As part of my on-going review of /help/en/, I'm now trying to reconcile the names of hardware help pages. They appear (or don't appear) in the sidebar that appears on many help pages (by "including" /help/en/parts/SidebarSupportedHardware.shtml), in the Help TOC, in the Help Index, and on the page /help/en/html/hardware/index.shtml. Some anomalies are easy to fix (inverting two words, misspelling, different abbreviations - all of which could be confusing to users). Others are a case of some hardware not appearing in all four places (there are 7 items that appear in the sidebar but not in the TOC, 2 that appear in the TOC but no where else, 3 that don't appear on the hardware index page, etc.). A couple of situations where I would appreciate input:

(1) Placeholder page https://www.jmri.org/help/en/html/hardware/anyma/index.shtml is referenced in the TOC, but not anywhere else. Is DMX something JMRI supports? Should I leave this page, delete, include in all appropriate places?

(2) Help page https://www.jmri.org/help/en/html/hardware/dcc4pc/index.shtml is referenced on the hardware/index.shtml but no where else. Should I include it in all appropriate places?

(3) The overall list of supported hardware is quite long (47 items already referenced, and possibly a dozen more manufacturers or hardware should be listed) so I would like to categorize them as a way of making lists easier to navigate. Here is my proposed categorization:
Multi-purpose:
Example: Digitrax, Arduinos
Networks and protocols:
Example: CAN Bus, MERG CBUS, OpenLCC, Digi XBee, LocoNet, Modbus, MQTT, C/MRI
Command Stations:
Example: SPROG, ESU ECoS, MRC, DCC++
Accessory devices:
Example: DCC Specialties, OakTree Systems, Arduinos
I am not familiar with all 47 hardware items so will no doubt need some interpretation on where things go, but how does this categorization sound so far? I'm happy to provide my list so far to anyone who wants to take a go at it.
--
Bob Jacobsen
@BobJacobsen


JerryG
 

Indeed, it does get complex, and yes, it should be a "web."  It's all about improving the UX (user experience) of ease of use and usefulness.

The sidebar was getting vary long with the full hardware list so I already shifted to only have a pointer to the list on the Tools and Layout Automation help pages, see here:   https://www.jmri.org/help/en/html/tools/.   I also thought of having a collapsible list, if someone could tell me how to do that (my JS skills aren't quite at that level).  Could we put a link to that code into the parts/SidebarSupportedHardare.shtml file?

But creating categories (as I did for the list of Tools) is one way to help reduce complexity as seen by the reader.  I was thinking to use the same categorization in the hardware/index.shtml page itself as well as in the sidebar.  I could also include a cross-index by vendor name on that page .

Digitrax and LocoNet are difficult ones.  The current help page has its own index and the sidebar has a long "local part" at the top:  https://www.jmri.org/help/en/html/hardware/loconet/Digitrax.shtml. In the Supported Hardware part of the sidebar, three things get highlighted by the JS (since all three of those point to the Digitrax help page).

Perhaps seeing the list and categories I have so far will help.  All items in my list already have a JMRI help page.  [Note from my earlier post about need to reconcile: 3 don't currently appear in the hardware/index.shtml page, 7 appear in the sidebar but not in the Help TOC, 2 appear in the TOC but no where else, and several don't have Help Index entries].  Two lists follow: alphabetical and sorted by categories [please tell me if any are wrong, or make other suggestions].

Hardware categories:  AD – Accessory Devices, CS – Command Station, MP – Multi-purpose, NP – Networks and protocols, PR - Programmers


H/W Cat

Name (as it appears in Sidebar part) or "To Be Added"

AD

[TBA: "Anyma DMX” - already in TOC]

MP

“Arduinos”

CS

“Atlas Commander”

AD

“Bachrus”

NP

“CAN Bus Networks”

NP

“C/MRI”

MP

“CTI Electronics (Acela)”

CS

“CVP EasyDCC”

CS

“DCC++”

 AD

[TBA: “Dcc4Pc” - already in hardware/index]

AD

“DCC Specialities”

NP

“Digi XBee”

CS 

“Digikeijs (Digirails)”

MP

“Digitrax”

PR

“Digitrax PR3” [suggested]

CS

“ESU ECoS”

CS

“Fleischmann Twin Center”

CS

“Hornby Elite”

MP

“Lenz”

CS

“Lionel TMCC”

NP

“LocoNet”

AD

“Maple Systems”

CS

“M&auml;rklin CS2”

NP

“MERG CBUS”

NP

“Modbus”

NP

“MQTT”

CS

“MRC”

NP

“NAC Services RPS”

CS

“NCE”

AD

“Oak Tree Systems”

CS

[TBA: “OpenDCC” - listed in XPressNet/index]

NP

“OpenLCB”

AD

“Protrak Grapevine”

PR

“QSI Quantum Programmer”

AD

“Pi Engineering RailDriver”

MP

“Raspberry Pi”

AD

[TBA:  “RFID Readers” - already in TOC]

CS

“Roco”

AD

[TBA:” TracTronics SECSI” - already in TOC]

CS, PR

“SPROG”

NP

“SRCP server”

CS

“TAMS Master Control”

CS

“Uhlenbrock Intellibox”

CS

“Viessmann Commander”

CS

“Wangrow System One”

AD

“WiFi Throttles”

NP

“X10”

CS

“Zimo MX-1”

CS

“ZTC”


and sorted by category:

H/W Cat

Name (as it appears in Sidebar part)

AD

[TBA:  “RFID Readers”]

AD

[TBA: “Anyma DMX”]

AD

[TBA: “Dcc4Pc”]

AD

[TBA:” TracTronics SECSI”]

AD

“Bachrus”

AD

“DCC Specialities (Hare)”

AD

“Maple Systems”

AD

“Oak Tree Systems”

AD

“Pi Engineering RailDriver”

AD

“Protrak Grapevine”

AD

“WiFi Throttles”

CS

{TBA: “OpenDCC”

CS

“Atlas Commander”

CS

“CVP EasyDCC”

CS

“DCC++”

CS

“Digikeijs (Digirails)”

CS

“ESU ECoS”

CS

“Fleischmann Twin Center”

CS

“Hornby Elite”

CS

“Lionel TMCC”

CS

“M&auml;rklin CS2”

CS

“MRC”

CS

“NCE”

CS

“Roco”

CS

“SPROG”

CS

“TAMS Master Control”

CS

“Uhlenbrock Intellibox”

CS

“Viessmann Commander”

CS

“Wangrow System One”

CS

“Zimo MX-1”

CS

“ZTC”

MP

“Arduinos”

MP

“CTI Electronics (Acela)”

MP

“Digitrax”

MP

“Lenz”

MP

“Raspberry Pi”

NP

“C/MRI”

NP

“CAN Bus Networks”

NP

“Digi XBee”

NP

“LocoNet”

NP

“MERG CBUS”

NP

“Modbus”

NP

“MQTT”

NP

“NAC Services RPS”

NP

“OpenLCB”

NP

“SRCP server”

NP

“X10”

PR

“Digitrax PR3”

PR

“QSI Quantum Programmer”

PR

“SPROG”




JerryG
 

I created a test version of hardware/index.shtml and sidebar to try out some of these ideas.  Not fully complete (some sections missing, some formatting and categorization issues), but check out:

https://www.jmri.org/help/en/html/hardware/indexnew.shtml

If you click “Supported Hardware” in the sidebar, you will get back to the current index and sidebar for quick comparison.

Let me know what you think, suggest improvements, errors, etc.

Thanks, Jerry


whmvd
 

Jerry,

That's a difficult beast to tame, it seems to me. I fear the function of a side-bar as a quick navigation menu gets lost in the combination of huge length and no fewer than four levels of headers (which do not indent, leaving the second and third levels, as non-links, strangely hanging about.

To prevent misunderstanding about what I mean with 'levels':
level 1: "Supported Hardware" etc.
level 2: "Devices, command stations, networks, and protocols:"
level 3: "Multi-Purpose:" etc.
level 4: "Arduino's" etc.

I'm aware that this is nothing to do with the work you have put in! All four were already there. And the whole thing was already more than a side-bar should strive to be, at least at one glance. Easiest to get shot of would be level 2, which could be usefully replaced by a tooltip when hovering over a level 1 header (this works, because level 2 appears once only, each time under a level 1 heading). Duplication of some level 4 items under multiple headers aggravates the situation, but the necessity is clear. I wonder if it would help (or would it hinder?) to get rid of the more detailed levels, leaving the top-level(s; 1-3) always visible but being able of expansion (plus sign is pretty well recognised). On expansion, its level 4 would open, while other, previously opened level 4s (now one at most) would close. This keeps the length well in check.

A further reduction in the list of supported hardware might be found by splitting it into two: a category actively maintained (JMRI developers who know about it and can fix it are around AND the manufacturer still supports its products) and another one 'historic' (it was seeing defunct Bachrus here that triggered this idea). Only the first category levl 4 entries in the side-bar, the second only as one level 4 entry: 'historic'.

Feel free to ignore me, by the way!
Wouter


On Sat, 25 Apr 2020 at 14:01, JerryG via groups.io <jerryg2003=aol.com@groups.io> wrote:
I created a test version of hardware/index.shtml and sidebar to try out some of these ideas.  Not fully complete (some sections missing, some formatting and categorization issues), but check out:

https://www.jmri.org/help/en/html/hardware/indexnew.shtml

If you click “Supported Hardware” in the sidebar, you will get back to the current index and sidebar for quick comparison.

Let me know what you think, suggest improvements, errors, etc.

Thanks, Jerry


JerryG
 

Great ideas Wouter!  I’ve been asking for someone to Help me add the +/collapse function - do you know how?  Everything I find on the web involves JS and web server changes that are beyond my current capabilities (although I can certainly add a line or two pointing to script files).  Ideally I would add those lines to help/en/parts/SidebarSupportedHardware.shtml which is now included in most sidebar files (and I would then update others to also include it as well) so propagates across the whole site.

Re four levels, I count only three.  What you list as level 2 is actually only a description line for Level 1.  I would make the +/collapse function for the lowest level (naming individual hardware items) only.  The Supported Hardware part of the Sidebar would be reduced to a reasonable length.  

As to the “no longer actively maintained” categorization of hardware, I actually see two categories there:
1. Manufacturer no longer sells
2. Manufacturer no longer supports
and I suppose that also means there is cross-category (for each) of:
- Support exists in JMRI but the developer no longer maintains (which could occur for either 1 or 2).

Are there developers out there who can tell me which are which and I will gladly update the page and sidebar appropriately?

Thanks, Jerry


Randall Wood <rhwood@...>
 

There are only two categories of maintained hardware in JMRI that you need to be concerned about:
- a JMRI developer has hardware and tests against
- developers do not have hardware and/or do not test against
This is completely unrelated to whether or not a manufacturer sells or supports a type of hardware, and I really don’t think we want the maintenance burden of tracking changes in what a manufacturer sells, or if a manufacturer is in business.

Randall

On Apr 25, 2020, at 11:06, JerryG via groups.io <jerryg2003@...> wrote:

Great ideas Wouter!  I’ve been asking for someone to Help me add the +/collapse function - do you know how?  Everything I find on the web involves JS and web server changes that are beyond my current capabilities (although I can certainly add a line or two pointing to script files).  Ideally I would add those lines to help/en/parts/SidebarSupportedHardware.shtml which is now included in most sidebar files (and I would then update others to also include it as well) so propagates across the whole site.

Re four levels, I count only three.  What you list as level 2 is actually only a description line for Level 1.  I would make the +/collapse function for the lowest level (naming individual hardware items) only.  The Supported Hardware part of the Sidebar would be reduced to a reasonable length.  

As to the “no longer actively maintained” categorization of hardware, I actually see two categories there:
1. Manufacturer no longer sells
2. Manufacturer no longer supports
and I suppose that also means there is cross-category (for each) of:
- Support exists in JMRI but the developer no longer maintains (which could occur for either 1 or 2).

Are there developers out there who can tell me which are which and I will gladly update the page and sidebar appropriately?

Thanks, Jerry


whmvd
 

Hi Jerry,

That second level, with its different font, is really not something that 'fits' in the sidebar concept. If it's description, it should be on the target page rather than in the sidebar, OR there should be a healthy looking way to incorporated it. Even just unifying the font would help a lot (as non-links there's be an easily perceptible difference to the level 1 headers anyway. Or it could pop out with the expansion. Maybe. Some careful consideration called for, I think, and if there are different sidebars on other pages, it would be good to look if they'd fit well into whatever mold is chosen here.

The last years of my active career in IT I had much to do with javascript. But before you rejoice: it was the reason I chucked it in. My brain refused to bend to the quirks, idiocies and general badness that the whole javascript mess involved (ahhhh, even writing this feels good!), and that's before even addressing how different browsers react. The constant fight to get it to do the same on all platforms was no fun at all, and I promised myself that I would never, ever touch javascript again. And I won't! I like Java well enough, I'm happy with SQL, C, C++, Unix shell-script etc. but until we get a sort of web-design 2.0 I'm out of front-end. And that web-design 2.0 had better not be yet another shell around javascript and html, but an actual fresh start. It'll happen within ten years, I'm sure. But it needs to be flexible, sturdy, immutable (so the likes of Microsoft an't get their grubby little fingers on it to make it awful once again), workable and easy to get into. All the current front-end stuff is not.

Hey? How did this turn into a rant? Never meant for that to happen! The auto-pilot took over. Sorry.

So anyway.

I don't think there'll be a need to be very religious about which hardware to move off the 'current' list. General consensus will do the trick better than criteria which will need to be adjusted time and again if the results seriously displease somebody.

Wouter


On Sat, 25 Apr 2020 at 16:06, JerryG via groups.io <jerryg2003=aol.com@groups.io> wrote:
Great ideas Wouter!  I’ve been asking for someone to Help me add the +/collapse function - do you know how?  Everything I find on the web involves JS and web server changes that are beyond my current capabilities (although I can certainly add a line or two pointing to script files).  Ideally I would add those lines to help/en/parts/SidebarSupportedHardware.shtml which is now included in most sidebar files (and I would then update others to also include it as well) so propagates across the whole site.

Re four levels, I count only three.  What you list as level 2 is actually only a description line for Level 1.  I would make the +/collapse function for the lowest level (naming individual hardware items) only.  The Supported Hardware part of the Sidebar would be reduced to a reasonable length.  

As to the “no longer actively maintained” categorization of hardware, I actually see two categories there:
1. Manufacturer no longer sells
2. Manufacturer no longer supports
and I suppose that also means there is cross-category (for each) of:
- Support exists in JMRI but the developer no longer maintains (which could occur for either 1 or 2).

Are there developers out there who can tell me which are which and I will gladly update the page and sidebar appropriately?

Thanks, Jerry


JerryG
 

Randall -

Got it.  Any ideas on how we find out if there is any listed hardware that developers do not have or do not test against?  All the hardware I have listed have help pages in the current help/web site, most with significant information, with the exception of Anyma DMX’s page which is simply a call for someone to write a page!  https://www.jmri.org/help/en/html/hardware/anyma/index.shtml  (the link on this page to “naming Anyma outputs” is non-existent).

Thanks, Jerry 


Randall Wood <rhwood@...>
 

This may sound facetious, but it is very serious suggestion: list all hardware as unsupported and let others fix it.

In detail that means: 1. List all hardware as unsupported/untested/believed-to-have-worked-at-one-time/your-milage-may-vary/whatever-language-you-decide-to-use 2. Get that checked into JMRI/master 3. Let the developers and others who do test hardware (i.e. who make it supported) submit individual pull requests to move hardware they do support into the supported list

This identifies which hardware the JMRI project did maintain an ability to support, but no longer does so. (I would consider someone who is willing to call out a piece of hardware as mis-categorized on this mailing list, but unwilling to use GitHub to submit a PR to address that, as not maintaining JMRI's support for that hardware, which is why I emphasized hardware they do support in step 3 above.)


whmvd
 

Randall,

I would agree, but for the effect it will have on people suddenly finding their hardware categorised as 'unsupported' and panicking. If they don't check back on the forum, they may feel forced into a totally unnecessary change to another system, or (milder) cause a rather large number of requests on the groups.io page. An initial guess would surely prevent the need to be quite so draconian? Who'd even DREAM of (say) Digitrax and NCE being marked as unsupported?

Wouter


On Sun, 26 Apr 2020 at 16:33, Randall Wood via groups.io <rhwood=mac.com@groups.io> wrote:

This may sound facetious, but it is very serious suggestion: list all hardware as unsupported and let others fix it.

In detail that means: 1. List all hardware as unsupported/untested/believed-to-have-worked-at-one-time/your-milage-may-vary/whatever-language-you-decide-to-use 2. Get that checked into JMRI/master 3. Let the developers and others who do test hardware (i.e. who make it supported) submit individual pull requests to move hardware they do support into the supported list

This identifies which hardware the JMRI project did maintain an ability to support, but no longer does so. (I would consider someone who is willing to call out a piece of hardware as mis-categorized on this mailing list, but unwilling to use GitHub to submit a PR to address that, as not maintaining JMRI's support for that hardware, which is why I emphasized hardware they do support in step 3 above.)


Randall Wood <rhwood@...>
 


On 26-Apr-2020, at 12:45, whmvd <vandoornw@...> wrote:

Randall,

I would agree, but for the effect it will have on people suddenly finding their hardware categorised as 'unsupported' and panicking. If they don't check back on the forum, they may feel forced into a totally unnecessary change to another system, or (milder) cause a rather large number of requests on the groups.io page. An initial guess would surely prevent the need to be quite so draconian? Who'd even DREAM of (say) Digitrax and NCE being marked as unsupported?

If no developer owns up to supporting Digitrax or NCE systems, I would leave those marked as unsupported. For systems maintained by active developers, I’d assume it would be at most a day or two before a system marked as unsupported is moved to the supported list, and this won’t have a significant impact.

Wouter

On Sun, 26 Apr 2020 at 16:33, Randall Wood via groups.io <rhwood=mac.com@groups.io> wrote:

This may sound facetious, but it is very serious suggestion: list all hardware as unsupported and let others fix it.

In detail that means: 1. List all hardware as unsupported/untested/believed-to-have-worked-at-one-time/your-milage-may-vary/whatever-language-you-decide-to-use 2. Get that checked into JMRI/master 3. Let the developers and others who do test hardware (i.e. who make it supported) submit individual pull requests to move hardware they do support into the supported list

This identifies which hardware the JMRI project did maintain an ability to support, but no longer does so. (I would consider someone who is willing to call out a piece of hardware as mis-categorized on this mailing list, but unwilling to use GitHub to submit a PR to address that, as not maintaining JMRI's support for that hardware, which is why I emphasized hardware they do support in step 3 above.)





Bob Jacobsen
 

I’m not sure that discriminator is all that useful. Several of the JMRI system were initially created and put in operation without any hands-on hardware: EasyDCC, Maple, Grapevine, even the first version of C/MRI. It’s easier to have hands-on hardware, but it’s not strictly necessary. In some cases, it’s not even sufficient.

You could look at the last dates that the code for each system changed, but some of the changes are due to general maintenance. And a system that’s not changing doesn’t mean it’s not being used. It might just mean it works well enough (i.e EasyDCC, which I think hasn’t a functional change in years, but has a bunch of users)

Maybe what matters most is whether there’s somebody on jmriusers who is able and willing to give good answers to questions.

Bob


On Apr 25, 2020, at 11:16 AM, JerryG via groups.io <jerryg2003=aol.com@groups.io> wrote:

Randall -

Got it. Any ideas on how we find out if there is any listed hardware that developers do not have or do not test against? All the hardware I have listed have help pages in the current help/web site, most with significant information, with the exception of Anyma DMX’s page which is simply a call for someone to write a page! https://www.jmri.org/help/en/html/hardware/anyma/index.shtml (the link on this page to “naming Anyma outputs” is non-existent).

Thanks, Jerry
--
Bob Jacobsen
@BobJacobsen


JerryG
 

Bob J said: “ Maybe what matters most is whether there’s somebody on jmriusers who is able and willing to give good answers to questions.”

What about if I added a line to each hardware manufacturer listed in hardware/index.shtml:

”The JMRIusers groups.io forum last discussed an issue related to this manufacturer on: [date]”

That will at least give an indication that support is available as Bob suggests. I’m willing to make a first pass of the user group for this, and will put a line in the section lead paragraph saying when dates below were last updated. Obviously could go stale quickly (doubt there is any real way to automate this), but at least it’s something.

Jerry


whmvd
 

Jerry,

For exactly the reason you mention (information going stale without automation or somebody updating this manually every hour) that would be worse than unhelpful. Because it would falsely give the impression of the group being inactive!

Wouter


On Thu, 30 Apr 2020, 01:34 JerryG via groups.io, <jerryg2003=aol.com@groups.io> wrote:
Bob J said: “ Maybe what matters most is whether there’s somebody on jmriusers who is able and willing to give good answers to questions.”

What about if I added a line to each hardware manufacturer listed in hardware/index.shtml:

”The JMRIusers groups.io forum last discussed an issue related to this manufacturer on: [date]”

That will at least give an indication that support is available as Bob suggests. I’m willing to make a first pass of the user group for this, and will put a line in the section lead paragraph saying when dates below were last updated. Obviously could go stale quickly (doubt there is any real way to automate this), but at least it’s something.

Jerry


JerryG
 

Gentlemen:

Having had a chance to digest all your input, I created another test version of hardware/index.shtml. 

https://www.jmri.org/help/en/html/hardware/indexnew.shtml

I kept the current sidebar (long alpha list) and added a category list to the top of the index page itself.  Note that the long alpha list in the sidebar should only appear when you are looking at hardware pages.  I've changed all (most?) other help pages to have only a simple pointer and description to the supported hardware area (see for example https://www.jmri.org/help/en/html/tools/ for this version of the sidebar).  For now, I've given up on the idea of somehow saying what support is or is not current.  I believe these changes achieve a good compromise of various suggestions.

If you click “Supported Hardware” in the sidebar on this test page, you will get back to the current index page for quick comparison.

Let me know what you think, suggest improvements, errors, etc. and I will then fix and promote to production.

Thanks for your input, Jerry


Peter Ulvestad
 

Digitrax PR4 is missing from programmers (PR3 is there)
https://www.jmri.org/help/en/html/hardware/loconet/PR4.shtml
It's also not listed in Digitrax under Multi-purpose hardware
(not on old page either).

--
Peter Ulvestad

JMRI Users Group Moderator - http://www.jmri.org ( http://www.jmri.org )
Tam Valley Group Moderator - https://tamvalleydepot.com/ ( http://tamvalleydepot.com/ )
Sprog-DCC Group Moderator - http://www.sprog-dcc.co.uk/ ( http://www.sprog-dcc.co.uk/ )
Edmonton Model Railroad Association - http://www.emra.club/


JerryG
 

I have integrated all comments received to date and promoted a version to the public site:

https://www.jmri.org/help/en/html/hardware/index.shtml

The work encompasses:
0. Reconcile and include all hardware found in prior page, TOC, sidebar, help pages, etc. to all places. Seven additions in total.
1. Category list near top of page with category words linked to appropriate parts of this page, individual items linked to their individual help pages.
2. Text and links from prior existing index.shtml then sorted alpha within category. Some additions as part of reconciliation.
3. Full alpha list in sidebar, as previously.  2 line header only in sidebars of non-hardware pages.
4. Instructions on how to update all this when new hardware added, put to  https://www.jmri.org/help/en/html/doc/Technical/Help.shtml#hwhelp
5. In process: additions to TOC and Index as necessary.

Thanks all for your help with improving help. [This topic “complete”]
Jerry