search

ArctosDB / documentation-wiki

Arctos Documentation and How-To Guides
https://handbook.arctosdb.org
GNU General Public License v3.0
13 stars 13 forks source link

table column documentation #213

Open dustymc opened 3 years ago

dustymc commented 3 years ago

SABI Goal Documentation sprints, community outreach with GBIF, iDigBio, TDWG

@Jegelewicz

https://github.com/ArctosDB/documentation-wiki/blob/gh-pages/_how_to/How-to-Bulkload-Parts.markdown

  1. It's wrong - "Arctos will automatically assign the next available catalog number if this field is left blank." is only true for some values of https://arctos.database.museum/info/ctDocumentation.cfm?table=ctcatalog_number_format
  2. It's redundant with https://handbook.arctosdb.org/documentation/bulkloader.html#fields
  3. https://handbook.arctosdb.org/documentation/bulkloader.html#fields is almost certainly wrong/outdated/etc.

I might fix one of those if I notice a problem, I'm probably not going to fix both (even if I want to, I'll never find them both).

I have a table used for the table browser (which might even serve as a UI)

                  Table "public.arctos_table_columns"
   Column    |          Type           | Collation | Nullable | Default 
-------------+-------------------------+-----------+----------+---------
 table_name  | character varying(255)  |           | not null | 
 column_name | character varying(255)  |           | not null | 
 description | character varying(4000) |           |          |

which is nice because it's internal, but also not-so-nice because it's not terribly accessible, isn't great at formatting, etc., etc. I could throw an API up against it very quickly, which is worth something.

We've been looking for a way to document table columns forever, I'm not thrilled with anything we've tried, don't have any great ideas, but maybe now's a good time to step back and think about this.

Jegelewicz commented 3 years ago

That's old stuff that I copied over from another document. I haven't gotten to it yet....thus the "under construction" bear.

Jegelewicz commented 3 years ago

Maybe we aren't looking at the same thing?

dustymc commented 3 years ago

copied over from another document.

I'd not be at all surprised if there's a 3rd copy out there somewhere - that's my point here!

Maybe Google Sheets? Does it save a flavor of HTML that the handbook can deal with? Then it would "just" be a matter of getting everyone to edit the spreadsheet and not the HTML.....

Jegelewicz commented 3 years ago

What? I am editing in the documentation wiki repo - why would there be anything anywhere else?

Jegelewicz commented 3 years ago

@dustymc lets chat about this on Monday during your office hour.

Right now some of the stuff in "Documentation" seems to really belong in either a How To or Best Practice. I'd like to stick with "technical stuff" in Documentation: what it is, what it does, and leave the rest elsewhere.

And I agree that we should make use of what you already have and build that into the Documentation so that we aren't doing things twice (and often getting it wrong in one place or the other).

a table used for the table browser (which might even serve as a UI)

which is nice because it's internal, but also not-so-nice because it's not terribly accessible, isn't great at formatting, etc., etc. I could throw an API up against it very quickly, which is worth something.

Agree! Maybe we can figure out a way for us to make it more accessible so that we can just use what you already do as part of your workflow.

Jegelewicz commented 3 years ago

@Jegelewicz to look at possible ways we can make use of the table browser to make it easier to create technical documentation.

Ideas include: