Documentation and Tutorial Workflow Plan

This is our current working draft of a documentation/tutorial plan for ExoCTK.

Where can I find the current documentation/tutorials?

When you're beginning from scratch on a subpackage or project for ExoCTK we ask that you also keep in mind your documentation and user tutorials.

Where can you find examples of our various types of documentation?

• Within our package we provide blurbs in the README to aid users in understanding the different packages available: https://github.com/ExoCTK/exoctk

• On our website we provide users information they need to properly use our tools - usually on the individual tool page: https://exoctk.stsci.edu/

• At ReadtheDocs we host documentation about the specifics of the code, this is a current work in progress as we update our subpackages: https://exoctk.readthedocs.io/en/latest/

• User tutorials are being developed as Jupyter notebooks available within the exoctk code here: https://github.com/ExoCTK/exoctk/tree/master/exoctk/notebooks

As a code developer on this project, what do I need to do?

Your responsibility is to aid in creating and distributing the proper documentation. For the current plan, we ask that you take the lead on updating the README.rst available on github as well as develop your own Jupyter notebook to aid users in running your code.

DO YOUR UPDATES ADD A SUB-PACKAGE OR AN APP PAGE TO OUR WEBSITE?

YOU MAY NEED TO UPDATE DOCUMENTATION!

Following your updates please contact the current documentation editor and inform them of your updates or new subpackage. From there the ReadtheDocs pages can be appropriately updated to match our current structure.

Often a developer will also update the website with a new tool for a subpackage, please coordinate with the documentation handler regarding that to ensure there are no miscommunications regarding the information provided from one of our sources vs. the others.

How do I make this easy for myself and others?

When you begin a new subpackage or start making changes (large or small) to the codes it may be appropriate to tag the documentation editor in your PR or issue!

From there it may make sense to make a secondary issue to track the various areas of documentation that need to be updated - the editor is here to help and ensure that all resources we provide users are updated in a timely manner to match what we are actually providing.