Tweaking wiki table docs

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Tweaking wiki table docs

Karl O. Pinc
Hi,

In the process of understanding chado I'm reading
a lot of wiki pages.  I'm going to make some
edits to some table descriptions, starting with
the General module and thought I'd mention
a documentation style I'd like to introduce.

I find it helpful to begin table definitions
with a phrase like "The foo table contains
one row per" and then go on with a
brief description of the entity represented
by the row.  This is a bit more chatty than
the current style, but has the advantage of
forcing a declaration of just what the row
represents.  I feel it also makes it a
little easier on the brain for people
on introduction to the software.

As an example, the General module db table's
first sentence would change from:

  A database authority.

To

  The db table contains one row per database
  authority, that is, one row per curator/creator of
  bioinformatic data collections.

I've no plans to go through the docs and
consistently make this change everywhere
and don't want to surprise anyone
with this change.

I'm going to go ahead and make a couple
of these changes now.  They can be rolled
back if people don't like the style.

Regards,

Karl <[hidden email]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

------------------------------------------------------------------------------
Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and their
applications. Written by three acclaimed leaders in the field,
this first edition is now available. Download your free book today!
http://p.sf.net/sfu/13534_NeoTech
_______________________________________________
Gmod-schema mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gmod-schema
Reply | Threaded
Open this post in threaded view
|

Re: Tweaking wiki table docs

Scott Cain
Hi Karl,

I'm fine with that style, as it is quite a bit more descriptive.  Ideally, I'd like to see the change take place in the SQL source (so the various SQL files buried in schema/chado/modules/*/*.sql), as the wiki pages are supposed to be automatically generated from the source SQL.  The problem (ie, that "supposed to be" part) is that it is a royal PITA keeping the wiki and the SQL files synced.

Scott



On Thu, Mar 13, 2014 at 4:27 PM, Karl O. Pinc <[hidden email]> wrote:
Hi,

In the process of understanding chado I'm reading
a lot of wiki pages.  I'm going to make some
edits to some table descriptions, starting with
the General module and thought I'd mention
a documentation style I'd like to introduce.

I find it helpful to begin table definitions
with a phrase like "The foo table contains
one row per" and then go on with a
brief description of the entity represented
by the row.  This is a bit more chatty than
the current style, but has the advantage of
forcing a declaration of just what the row
represents.  I feel it also makes it a
little easier on the brain for people
on introduction to the software.

As an example, the General module db table's
first sentence would change from:

  A database authority.

To

  The db table contains one row per database
  authority, that is, one row per curator/creator of
  bioinformatic data collections.

I've no plans to go through the docs and
consistently make this change everywhere
and don't want to surprise anyone
with this change.

I'm going to go ahead and make a couple
of these changes now.  They can be rolled
back if people don't like the style.

Regards,

Karl <[hidden email]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

------------------------------------------------------------------------------
Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and their
applications. Written by three acclaimed leaders in the field,
this first edition is now available. Download your free book today!
http://p.sf.net/sfu/13534_NeoTech
_______________________________________________
Gmod-schema mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gmod-schema



--
------------------------------------------------------------------------
Scott Cain, Ph. D.                                   scott at scottcain dot net
GMOD Coordinator (http://gmod.org/)                     216-392-3087
Ontario Institute for Cancer Research

------------------------------------------------------------------------------
Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and their
applications. Written by three acclaimed leaders in the field,
this first edition is now available. Download your free book today!
http://p.sf.net/sfu/13534_NeoTech
_______________________________________________
Gmod-schema mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gmod-schema
Reply | Threaded
Open this post in threaded view
|

Re: Tweaking wiki table docs

Karl O. Pinc
On 03/17/2014 01:43:08 PM, Scott Cain wrote:

> Hi Karl,
>
> I'm fine with that style, as it is quite a bit more descriptive.
> Ideally,
> I'd like to see the change take place in the SQL source (so the
> various SQL
> files buried in schema/chado/modules/*/*.sql), as the wiki pages are
> supposed to be automatically generated from the source SQL.  The
> problem
> (ie, that "supposed to be" part) is that it is a royal PITA keeping
> the
> wiki and the SQL files synced.

I can patch the .sql files in my git repo.  
(Is there any expectation that
my patches might be pulled in the foreseeable future?)


Karl <[hidden email]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

------------------------------------------------------------------------------
Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and their
applications. Written by three acclaimed leaders in the field,
this first edition is now available. Download your free book today!
http://p.sf.net/sfu/13534_NeoTech
_______________________________________________
Gmod-schema mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gmod-schema
Reply | Threaded
Open this post in threaded view
|

Re: Tweaking wiki table docs

Karl O. Pinc
On 03/17/2014 03:49:28 PM, Karl O. Pinc wrote:

> On 03/17/2014 01:43:08 PM, Scott Cain wrote:
> > Hi Karl,
> >
> > I'm fine with that style, as it is quite a bit more descriptive.
> > Ideally,
> > I'd like to see the change take place in the SQL source (so the
> > various SQL
> > files buried in schema/chado/modules/*/*.sql), as the wiki pages
> are
> > supposed to be automatically generated from the source SQL.  The
> > problem
> > (ie, that "supposed to be" part) is that it is a royal PITA keeping
> > the
> > wiki and the SQL files synced.
>
> I can patch the .sql files in my git repo.  

What's with the *.html files?


Karl <[hidden email]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

------------------------------------------------------------------------------
Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and their
applications. Written by three acclaimed leaders in the field,
this first edition is now available. Download your free book today!
http://p.sf.net/sfu/13534_NeoTech
_______________________________________________
Gmod-schema mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gmod-schema
Reply | Threaded
Open this post in threaded view
|

Re: Tweaking wiki table docs

Karl O. Pinc
In reply to this post by Karl O. Pinc
On 03/17/2014 03:49:28 PM, Karl O. Pinc wrote:

> On 03/17/2014 01:43:08 PM, Scott Cain wrote:
> > Hi Karl,
> >
> > I'm fine with that style, as it is quite a bit more descriptive.
> > Ideally,
> > I'd like to see the change take place in the SQL source (so the
> > various SQL
> > files buried in schema/chado/modules/*/*.sql), as the wiki pages
> are
> > supposed to be automatically generated from the source SQL.  The
> > problem
> > (ie, that "supposed to be" part) is that it is a royal PITA keeping
> > the
> > wiki and the SQL files synced.
>
> I can patch the .sql files in my git repo.  

I just pushed these changes to a new branch
"tabledocs".

https://github.com/kpinc/chado


What's with the line wrapping in the .sql file comments?
The "db" table is line wrapped, the "dbxref" table is not.


Karl <[hidden email]>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

------------------------------------------------------------------------------
Learn Graph Databases - Download FREE O'Reilly Book
"Graph Databases" is the definitive new guide to graph databases and their
applications. Written by three acclaimed leaders in the field,
this first edition is now available. Download your free book today!
http://p.sf.net/sfu/13534_NeoTech
_______________________________________________
Gmod-schema mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/gmod-schema