Related applications in our help pages
Jerry Grochow (@jerryg2003 on GitHub) has been doing some very nice work on the navigation for the web site, focused mostly on rationalizing the sidebars.
In the process, a question came up about web pages for things related to JMRI such as Manifest Creator, TrainCrew and others. See Issue 7887 https://github.com/JMRI/JMRI/issues/7887
These things not JMRI, but they’re related. JMRI users might come to our web site to learn more about them. On the other hand, it might be hard to maintain and update correct info.
Sometimes these appear in the sidebar under “The Apps” (see the TrainCrew page). Other times, they’re there in other forms.
Jerry suggested an Add-On Applications section (See also https://www.jmri.org/help/en/html/apps/index.shtml ) Randall was concerned about having individual pages (see discussion in https://github.com/JMRI/JMRI/issues/7887)
The above run “with” JMRI in some sense, but that’s a somewhat fuzzy boundary. See also:
(But we don’t have a page for the AnyRail export)
And note that we moved from having individual pages for clients like WiThrottle, Engine Driver, DigiTrainsPro, etc to having a single page: https://www.jmri.org/help/en/package/jmri/jmrit/withrottle/UserInterface.shtml
I think we should sort this out. What do we have for these things on our web? What do we call them? Do we let proponents of outside-JMRI-but-related things put some intro text on pages in the JMRI web? Link to OJBR pages somehow? A composite page with some summary info and pointers? How much sidebar real estate should these get?
By working this out now, as Jerry is improving the navigation, we can get a more consistent and understandable web site.
I think the move to a single page summarizing known addons and tools we work
with is the right way, not whole pages for each. For the most part we should
have the link to the other product and a short blurb about it. I would see
there are two classes of these external products, I'll call them one way and
two way tools.
Things like manifest creator, which just takes JMRI output and does
something with it, is a one way tool, we give it data. The AnyRail would be
another example, one way, we read something from it.
The whole world of things using the WiThrottle interface are clearly two way
tools. We exchange data with them.
One area that might break this is where we need to document how to use some
tool, like configuration issues within JMRI, that are not documented on the
site of the tool. To be useful and reduce the support issues, sometimes
things need to be documented and if the folks with the tool aren't up to the
task, it is worth our time to put something somewhere.
-Ken Cameron, Member JMRI Dev Team
I agree with Ken with the exception of the last paragraph.
I think configuration issues should be left with the tool site.
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/
[Apologies for the long post, but I do propose a solution...]
May I add additional issues into the mix: I found a page titled “JMRI Partners” (https://www.jmri.org/community/connections/ ) although I haven’t yet found where it links from. The term “partner” typically implies a relationship, perhaps formalized in an agreement. This page lists XtrkCADReader, Model Railroad Manager, and CATS. Does JMRI have such relationships?
CATS is the only one of these also listed as an Add-On Application (on the JMRI Applications page https://www.jmri.org/help/en/html/apps/index.shtml) where it is listed along with Manifest Creator and TrainCrew (which are not listed as JMRI Partner apps).
So now we have JMRI Partner (applications) and Add-on Applications.
The situation is further muddled in that they link to either (1) pages in JMRI.org/community/connections (2) pages within the main JMRI.org site (e.g. https://www.jmri.org/help/en/html/doc/Technical/CATS.shtml) or (3) external sites. Furthermore, there is no consistency and some applications go to internal pages from one place and external pages from another.
1. Have a section on the JMRI applications page for “additional applications with JMRI connections.” This would replace what is currently called “add on applications.“ A sentence or two about the application can be included here and the name of the application can link either to an external website or to a page in the JMRI.org/community/connections area.
2. Retire the page entitled “JMRI partners” and move the appropriate information to the above.
3. Move information about these additional applications tp JMRI.org/community/connections part of the hierarchy from wherever they exist with JMRI.org today.
4. Update sidebarapplications.shtml part to include a link to the additional applications area listing.
5. Create a new help/en/’part called additionalapplications.shtml that can be included in appropriate sidebars as necessary.
While it is certainly possible to additionally make a distinction between one-way applications and two-way, I’m not sure that would make this listing of additional applications more useful. There is also the issue of commercial applications (some of which have a free version, but ultimately they want money for use of their products) and open source applications. If an application is open source, I would propose to note that next to its name in the additional applications listing.
Adding a new application would now involve three steps:
1. Add its name and a few sentences to /help/en/html/apps/index.shtml. Next
2. If desired, add help pages to jmri.org/community/connections/[name of applications Ken ]. This is where either “we” or “they” can document any special considerations Ken wants “we” and Peter wants “they” to deal with.
3. Link to these or external website off the name.
4. Add a link within additionalapplications.shtml so it will show up in any sidebars that include this part.
Hopefully, this addresses issues of ease of use, ease of maintenance, ownership, etc. and, with a clearly identified place to list additional connected applications, and some visibility via sidebars, perhaps we’ll scare up some more of interest.
If there is general agreement, I’ll start down this path. If not, please propose an alternative.
Thanks for the detailed, thought-through post!
First, a couple details. There’s another repository (JMRI/website at https://github.com/JMRI/website ) that’s meant to hold parts of the web site that don’t need to appear on JMRI’s self-contained help. (That was important a long time ago when JMRI had to stay a smaller download). That has some references to community/connections:
JMRI/projects/website/ % grep -r community/connections .
./index.shtml: <h2><a href="community/connections/XtrkCadReader/index.shtml">XTrackCAD and JMRI</a></h2>
./index.shtml: <a href="community/connections/XtrkCadReader/index.shtml"><img src="images/xtracadreader.png"
./index.shtml: <a href="community/connections/XtrkCadReader/index.shtml">XtrkCadReader</a>
./community/connections/Sidebar: <li><a href="/community/connections/XtrkCadReader/index.shtml">XtrkCadReader</a>
./community/connections/Sidebar: <li><a href="/community/connections/CATS.shtml">CATS</a>
As to the proposal below for handling “things that work with JMRI”, it sounds quite reasonable to me. It makes a simple (!), consistent (!!) and easy-to-maintain and extend (!!!) way to go forward.
On Jan 9, 2020, at 10:46 AM, JerryG via Groups.Io <firstname.lastname@example.org> wrote:--
While I don't particularly relish the idea of having to deal with sidebars in two repositories, I do have a question about whether we would need to replicate the Parts directory in the website repository in order to "include" parts files in the HTML of the sidebar.shtml files in the website directory. If so, I think I can handle this (within my limited skill set...). Let me know.
Has anyone thought about whether merging the two repositories makes any sense (or is even possible)? At least for the website and help files, maintenance would certainly be easier. Or perhaps just keeping the website repository for the manuals (and renaming it).
P.S. I thought I had already replied to your post, but I"m still on moderator-release so perhaps it is in the queue somewhere.