Chado Documentation Reorganization

From GMOD
Revision as of 21:11, 16 April 2008 by Clements (Talk | contribs)

Jump to: navigation, search

We are going to reorganize the Chado related documentation in this web site. Chado is the database schema of GMOD and it has quite a bit of documentation in this web site. However, the doc could be better organized and integrated. This page summaries the documentation we have, and then proposes (and solicits feedback on) a reorganization plan.

Once the work starts, this page will also describe how the work is going.


What Exists

This summarizes the major Chado related pages that existed when the reorganization began in early April 2008. It is not an exhaustive list of pages related to Chado. See the Chado Category for that.

Page Description Comments
Chado - Getting Started Sections:
1 Documentation;
2 Modules;
3 Installation;
4 Loading Data;
5 Contacts;
6 Pronunciation
Need to reconstruct it.
Chado Best Practices Description of how various sequence features can be represented in Chado. Has placeholders for genotypes, phenotypes and a few others. This be a good starting point for a how do you represent X in Chado page - a Chado Cookbook page.
Chado Doc Project Brian Osborne's call-to-arms to write "material that is very practical and specific" meaning "Best Practices" and "module pages". Brian broke Chado up into 8 workpackages and sent out a call for volunteers. 3 of the 8 packages have been claimed. I'll follow up on this once the first pass at the reorganization is done.
Chado FAQ Currently has 5 widely disparate questions. Split questions into FAQs and Chado Cookbook. Cookbook cover "How do you represent 'x' in Chado" questions, and FAQs handle everything else.
Chado Manual A high level, architectural view of Chado. Has 5 sections:
1) Intro (Modularity, Ontologies, Associated Software, Complexity and Detail, Data Integration, Support),
2) Modules,
3) Naming Conventions
4) Design Patterns,
5) DBMS Functions.
Explains chado from a database practitioners point of view.
Chado New Users This page, and its associated discussion page follow the learning curve for new Chado users learning the system at CSHL. A collection of user installation/experience logs would be darn useful. Create a template for this that encourages users to list things like versions used. This reduces the need to keep "Installing component X on platfrom Y" pages up to date for every possible combination. Just have a list of user log pages that detail X and Y.
Introduction to Chado An explanation of the Sequence module. Change the title. This is almost entirely about the Sequence module. Chris Mungall also indicates that this page is no longer current.
Sample Chado SQL Shows 8 or 9 queries. All but one of the queries involves the feature table. Integrate the SQL with the Chado Cookbook.
A Chado Case Study (pdf) The official publication about Chado. From ISMB/ECCB 2007.
Chado Manaul (PDF) A PDF Chado manual. The TOC is extensive, but many sections are empty. Much of this information has already been transfered to wiki pages. Sections with content:
1) DBMS Functions (see Chado Manual),
2) The General Module (see Chado Manual),
3) The CV Module (see Chado CV Module),
4) The Sequence Module (see Chado Sequence Module, Chado Best Practices), and
5) Chado Naming Conventions (see Chado Manual).
Add pointers to the PDF page to the wiki pages that now cover the same material.
Template:ChadoModules All the module documentation. There is a page for each module, and each page contains a complete physical description of each table and column. Many modules also have some explanatory text, as do many tables and columns. Keep and expand this.
GMOD Users A list of GMOD users. Has a column for Chado users. List users differently. Problem is maximizing usefulness without maximizing redundancy. Want
1) A list of users per component, including how they use it. For Chado this would include OS, OS release, DBMS, DBMS release, and list of modules in use.
2) List of all GMOD users with pointers to what components they use.
The overall list is high level; the component lists are detailed. Keeping them in synch, even though they are at different levels of detail, is the hard part.

Plan

A draft plan for how the documentation will be restructured.

  • Chado
    • Page that shows basically this outline and has a getting started section or link
    • Getting Started
  • Chado Database Administration
    • DBMS and OS Choice
    • Installing Chado
    • Maintaining Chado
      • Include performance tips and discussion of backups.
      • See also User Experiences with DBMS/OS combinations.
    • Accessing, Importing and Exporting Data
      • Various APIs, middleware solutions
      • Pointers to Apollo, GBrowse, etc connector pages
  • Using Chado
    • Chado Cookbook
      • Answers questions like "How do I do X in Chado". Pull a lot of these from E-mail list.
      • Fold SQL into this one. Expand it out to cover more than Sequence module.
    • Chado FAQ - Answers those recurring questions
    • Chado User Experiences
      • Who uses chado and how matrix.
      • High level user stories, such as ParameciumDB
      • Low-level "installing/using Chado on X using DBMS Y" logs/stories.

This proposal will be refined as we get feedback and the effort progresses.

Feedback

You are encouraged to provide feedback on this effort by

Note: Unless you request otherwise anything sent to the GMOD Help Desk or to the GMOD-Schema mailing list may be reproduced here.

Comments

Provide your feedback here!

Mechanics

Each page that is being modified, created or deleted as part of this effort will include the ChadoDocReorg template:

This page is being modified, created, or deleted as part of the Chado Documentation Reorganization effort.

This page may be unstable, or may be replaced with a redirect as a part of this effort. Once the Chado Documentation Reorganization is complete this page will become stable and this notice will be removed.

If you have any questions, comments, or suggestions on this effort please see the Feedback section of the Chado Documentation Reorganization page.

This will be placed at the top of the page, and tag the page as a member of the Chado Doc Reorg category. Once the project is done, all the template references, the template, and the Chado Doc Reorg category will be dropped.