Core goal: Documentation

laceysanderson commented 5 years ago

I wonder if moving the documentation for Chado into this repo via readthedocs would make documentation for chado more visible. Additionally, I think it would make it easier for contribution of "how to use chado" (i.e. best practices and/or just different methods). For example, the recent issue on mRNA/Gene versioning (https://github.com/tripal/tripal/issues/645) has shown multiple common ways in use -it would be great to document these! While we could put them on the gmod wiki, I worry these docs get lost there.

Reasons for including docs in github:

easy to tag an issue as needing updates to documentation which helps keeps the documentation up to date
makes it easier to find/navigate all the documentation without getting lost in all the other gmod docs
easy to contribute changes ("Edit in gihub" automatically creates a fork and PR)
allows us to curate docs which improves quality (I volunteer to keep up with this although I would Love help)
I've noticed moving Tripal docs to github makes me feel more rewarded for updating docs since people actually see I'm making updates

Downsides:

documentation in multiple places (gmod wiki, readthedocs, schemaspy). This could be mitigated by good external linking making readthedocs the primary source

ekcannon commented 5 years ago

I second the motion! It can be challenging for a Chado newbie to find relevant documentation, and some documentation, like best practices can be missed entirely.

bradfordcondon commented 5 years ago

@scottcain if this interests you i can volunteer to set this up.

bradfordcondon commented 5 years ago

the schema spy docs lacey built for reference https://laceysanderson.github.io/chado-docs/index.html

bradfordcondon commented 5 years ago

@bradfordcondon will stub out a RTD site in advance of the hackathon. From our discussion today, we won't remove the wiki. However, we will try to seperate out things that are complete guides and documentation from some of the discussion and unanswered questions that exist on the wiki.

bradfordcondon commented 5 years ago

status

Integrated with read the docs. I plan to make a PR once i've got the basic structure of what docs would go where mapped out. we'll deal with adding the schemaspy docs later (#36). Worth noting that the submodules have hteir own pages, but in some cases its tables of the schema documentation: in those cases we would want to either link out to schema spy or, evne better, somehow integrate the two pages.

Page listing

I think this listing is a great directory for what chado docs exist

http://gmod.org/wiki/Category:Chado

I think the general categories are:

Modules
core documentation (installation guide, manual)
site specific implementations ( x at flybase)
how-tos (http://gmod.org/wiki/Store_an_unigene_in_Chado_HOWTO)
perl tools (http://gmod.org/wiki/DBStag)
presentations

I think the goal is to get any general guides, module documentation and the best how-tos that focus on the schema itself into one place in the RTD.

Resources/thoughts

Possible resources: converting wiki to RST? https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Converting_Wiki_Documentation_to_Sphinx

something i dont understand: if the wiki is live, but we have a coded copy of the wiki at chado/doc what happens to changes made via the GUI-- do they get autocommited to the repo? Or would they be lost if we pushed the wiki on this repo to the live wiki? Seems like there are definitely pages on the live wiki not on the local archived one, ie http://gmod.org/wiki/Sybil_Chado_Comparative_Genomics_Data

scottcain commented 5 years ago

@bradfordcondon About your last comment/wondering: no, things added to the wiki don't automatically make it back into the repo, which results in somewhat of a catch-22: syncing them manually is difficult, which makes me put it off, which makes it more difficult.

GMOD / Chado