Requesting Feedback and Support in Consolidating Source Code and Documentation

["McNanney, Douglas via Tech-talk" <tech-talk at aps.anl.gov>]

Hello All,

At this weeks documentathon, one of the tasks was to consolidate all publicly available EPICS software outside of EPICS Base here.

We understand that epics-controls.org has the Hardware Support and Soft Support pages which are still regularly used. This new page does not replace these pages, and they will remain up for the foreseeable future. However, we would like to start the discussion as to where to put everything, as ideally everything will move to one place. To begin to phrase an argument for each approach:

Moving Hardware and Software Support to RTD

Advantages

1. Making modifications to markdown tables through the epics-docs repository is much easier than editing the database used by the wordpress site. Anyone can submit a pull request to update, add or remove links.
   
2. RTD in general is easier to maintain than the wordpress site. The wordpress site is great for visibility, but not for technical documentation that is updated often.
   
3. Search is possible via CTRL+F, in addition to the RTD search feature, although this is slightly less elegant than the proper database search done on epics-controls.org

Disadvantages

1. Lack of a formal database search

Moving EPICS Related Software to epics-controls.org

Advantages

1. The related software page can exist next to the existing database browsers.
2. This will not break existing applications that read the db / webpage for lab-specific websites. I do not know the extent of this issue.
3. This supports a proper, easy to use search feature.
   

Disadvantages

1. Links are very difficult to update or remove. Most users cannot do this on their own.

There are clearly pros and cons to discuss here, and either approach will require some effort. However, having a consolidated index of available EPICS software would be incredibly helpful, especially to newcomers. The work is (mostly) done for consolidating external links - but we ultimately need to decide where they live long-term. I personally lean towards hosting these lists on RTD, as it would be easier for developers to promote their own projects via a simple pull-request. However, I realize I am a bit biased coming from the documentathon where we spent some time building up RTD. Either way, the epics-controls.org site is not going anywhere.

Now, back to the new listing on docs.epics-controls.org, the RTD page

If you have software you would like included or removed from this list, please submit a pull-request or issue on the epics-docs github page. Please also do so if you find any links are incorrect or outdated.

You may notice a few links are missing in these tables. This is either because source code / documentation has not been provided, found, or it is one of the projects that was previously hosted on BESSY's servers which have been recently taken down. So, this is also a call for someone to host documentation and source code for their projects - which are as follows:

 

pymsi
PEZCA
CA Watcher

There may be more, but these were identified from the old list on epics-controls.org - which will soon link to the RTD page above. Please reply if there is any interest in hosting these projects.

Thank you for reading this far. If you have any interest in this effort, your feedback would be greatly appreciated!

Best,

Doug McNanney (He/Him)
 Controls Engineer
 Facility for Rare Isotope Beams
 Michigan State University
 640 South Shaw Lane
 East Lansing, MI 48824, USA
 Tel. 517-908-7723
 Email: mcnanney at frib.msu.edu