Document-athon short report

[Timo Korhonen via Tech-talk <tech-talk at aps.anl.gov>]

Dear colleagues,

 

You may have been aware or noticed from tech-talk posts or even visiting the epics-controls.org website that last week we had the EPICS Documentathon at ESS.

 

Little bit over 20 people participated in the event, about 16 on-site here at European Spallation Source, and a number of people participating remotely.

 

A big THANK YOU to all the participants, as well as their managers who enabled the participation!

 

We were busily working on a number of topics related to EPICS documentation; here is a very short summary:

 

• Rémi Nicole presented the results of the recent survey about documentation, we used the results to guide our work: where to put the focus.
• We discussed how to make it easier for people to contribute to documentation, and created a contribution guide: https://docs.epics-controls.org/en/latest/CONTRIBUTING.html
• We ported documentation from the epics-controls.org website to docs.epics-controls.org, formatted to (mostly) Markdown and processed with the readthedocs.org build system. The hope is that this will make contributing and updating easier, as the (git-based) workflow is more familiar to many.
• A number of changes were done on the epics-controls site; more will be done. The basic idea is to keep that site as an entry point, with announcements, software download links, etc., but have the detail documentation on docs.epics-controls.org, linked from the parent site.
• These central sites will link to documentation of other components; we believe that (module) documentation should be kept close to the code rather than on a separate site. We try to make the process such that this is as easy as possible.
• Some content was updated, but the main focus this time was on creating the structure, workflow and removing duplication. We hope that the new workflow makes it much easier to contribute. Many updates are needed.
• Number of maintainers of the documentation sites increased a lot, so I hope we can merge in new contributions rather quickly.

 

Friday afternoon a quick calculation of the epics-docs project on github showed 33 pull requests, 22 merged, 11 to go; work was still ongoing so the final count is bigger.

And ~350 (unread) notification emails 😊 as of today morning.

 

There is a lot more to report, this is only a small fraction of what was going on. I will give a summary in the upcoming EPICS meeting attached to ICALEPCS.

 

Comments and questions are welcome and we are looking forward to the contributions from the community!

 

Best regards,

 

Timo (ESS)