Well... in true EPICS tradition, there is not only one but two ways how to contribute a how-to article!
To start, here is one link:
https://epics-controls.org/resources-and-support/documents/howto-documents/
For this one, the “how to contribute” would be like this:
-create yourself an account on the epics-controls.org website
and let us (Ralph, Andrew or myself) know that you want to contribute a how-to article. We will give you the correct “role” on the site. Just having an account does not let you do that much. But with the correct role you can also access instructions
on how to write and publish articles (those instructions contain more details than this short email.)
-learn a bit of WordPress. It is not that difficult, believe me. The (relatively) new editor is WYSIWYG and if you can write an email you can for sure use the editor as well.
-Create a new page, submit it to review workflow and as soon as one of the reviewers accepts the content, it will appear on the website.
But there is also another way and as far as I understand, this is the one that we agreed to go for in the long run:
First the link:
https://docs.epics-controls.org/projects/how-tos/en/latest/
(it is also linked from here :
https://epics-controls.org/resources-and-support/documents/ but probably not prominently enough.)
And the corresponding Github repo:
https://github.com/epics-docs/how-tos
This method uses readthedocs.org as a build and publishing provider. The process is roughly the following:
- learn basics of reStructuredText if you are not yet familiar with that format. Also some git skills are useful.
- fork the above repo and add a new article. Consult Ralph or myself to figure out where to put the new file if needed. All other related questions are also welcome.
- When you are done with editing, create a pull request. One of the project members will merge, and the document appears on the docs.epics-controls.org website.
- Or, you can ask to become a member in the how-tos (or epics-docs) project(s) so that you can commit directly to that project. Help is always welcome.
- There are some additional fine points like adding the new document to the index file, etc., but if you contribute the text I offer to take care of the rest (unless
I start getting hundreds of contributions…I consider that rather unlikely, though.)
The second way was created because we thought that this would be easier to get familiar with for people who work mostly in software, and the editing in the epics-controls website was a bit complicated earlier. Now the
new editor in WordPress is (IMHO) so easy that maybe it is not an issue anymore.
The other point was also that the second method can also host documentation produced by Doxygen and that would enable us to collect all the related docs under the same site.
I hope this gives some pointers. Comments, suggestions and, above all, contributions are welcome!
Best regards,
Timo