Documentation

[Jim Hokanson]

Hi all,

   I'm relatively new to the group. I've started working a bit on the analysis of movement patterns based on real worm recordings with the intention of eventually comparing this to the model's movements.

  Two things I've noticed as a newcomer.

1) There is a very welcoming atmosphere! I really appreciate that.

2) (the real topic of discussion) I am totally confused about the projects and the organization. 

Some questions:

1) Where are we putting documentation? It seems like there are random spreadsheets that can be found in various locations. There are gists here and notebook viewers there, a wiki in the OpenWorm repository, a "data folder" from the openworm website with many files that are completely unintelligible to me. I'm more than willing to help it just isn't clear where to even start and it seems like the Google Groups and word of mouth are the two official ways of documenting things which is easy but doesn't seem like a great idea.

2) Related to 1, where are we putting data and more importantly, documenting data sources? More on large data for another night. WIth data sources I think it is nice to have additional information that describes where the data has come from, how it's been processed/compiled, descriptions of the data (or pointers to it), or even just a contact person on who is considered to be in charge of the data (or at least knowledgeable about it).

3) What are the groups' current git policies, specifically related to data and documentation. I think GitHub wikis are open to anyone by default but can be restricted to collaborators. I personally think the interface is a bit awkward and tend to prefer Google Sites. Within GitHub I've started to prefer putting documentation in the repositories directly (I think it has a nicer interface) but that requires either collaborator access or pull requests, which is fine, it would just be useful to have somewhere that documents expected Github usage/behavior.

4) Who's working on what? What progress has been made? Who needs help? This has largely been the purview of issues but it might be helpful to have a centralized location for this organized by topic instead of needing to do a bunch of searching. 

Summary:

Documentation is always tough but as I'm learning new things I'm more than willing to help document and I'd rather go with the flow than do my own thing. 

Thanks,

Jim

[Mike Vella]

Hi Jim,

Thanks for the email - when you're deep into a project its easy to lose sight of what things look like to a newcomer.

1. As you observe we have three main places we keep everything: Dropbox, Github, Google docs. We are moving towards having most introductory documentation on the github wiki. Documentation specific to sub-projects will generally be found in the github repositories.
2. Adding metadata is definitely an important step, things are improving in this regard. However this is unfortunately a problem which pervades biology in general.

3. Data is generally not stored on github but rather on Dropbox. Project-wide documentation is stored on the OpenWorm repo and other repositories contain the documentation relevant to those sub-projects.We don't have a strictly defined git policy document, perhaps we should..

4. Who is working on what and the status they are at is covered by our github issues. Feel free to leave comments on these issues for clarification reqeuests etc.

As a general point the discussion list and github issues to my mind are the default way to get more information on the project.

Mike 

--
Visit us online at:
http://openworm.org
http://blog.openworm.org
http://github.com/openworm
http://twitter.com/openworm
https://plus.google.com/s/openworm
---
You received this message because you are subscribed to the Google Groups "OpenWorm-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openworm-discu...@googlegroups.com.
To post to this group, send email to openworm...@googlegroups.com.
Visit this group at http://groups.google.com/group/openworm-discuss.
To view this discussion on the web visit https://groups.google.com/d/msgid/openworm-discuss/3db71014-7f8e-4978-8cea-de70b985428b%40googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Stephen Larson]

Thanks Mike for the pointers.  

I do agree with Jim's basic premise that we could be doing more with documentation and I think we can't be reminded of this enough.  Thanks Jim for highlighting it.

It occurs to me that perhaps what the core team misses is the specialized knowledge that is a pre-requisite in understanding how to get started with the code bases.  

Are there folks out there would would give a +1 to the idea of getting more introductory material into our documentation to ease people in from different technical backgrounds into the project?

Thanks,

  Stephen

To view this discussion on the web visit https://groups.google.com/d/msgid/openworm-discuss/CAGKgUfUBE8_KO%2Bjh52Vx3P2qnChBqRzoSOL2J%2BsKrTSsVdberA%40mail.gmail.com.