Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

77%
+5 −0
Q&A How should I document a database schema?

I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look...

3 answers  ·  posted 10y ago by Monica Cellio‭  ·  edited 3y ago by Monica Cellio‭

#4: Post edited by user avatar Monica Cellio‭ · 2021-06-06T19:35:46Z (over 3 years ago)
trying to fix tags
  • I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look at what the database offers, and write their SQL queries. Think of something like [SEDE](http://data.stackexchange.com/help).
  • I could just give people the database schema, but that only tells you so much. For example, if a value is an integer but it's an enumeration (1 means this, 2 means that, 3 means this other thing, etc), you can't get that from the schema alone. So I need to produce some documentation for the tables and columns in the database, which also provides me the opportunity to present the information in whatever organizational structure makes the most sense for our users.
  • My question is: are there best practices for going from a DB schema to documentation? If this were an API, for example, then in some languages I could write inline comments that could be automatically turned into reference documentation using tools like Javadoc or Doxygen. Is there something like that for DB schemas, or would I have to write my own transformation tools (which isn't worth the effort for the size of this project)? Or do people writing schemas just inspect the schema and write separate documentation? Are there conventions for doing this? I'm an experienced technical writer but I'm new to databases.
  • (In case it matters, I need to deliver HTML. This is a volunteer project (not actually open-source, but along those lines) and I have no budget for tools.)
  • I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look at what the database offers, and write their SQL queries. Think of something like [SEDE](http://data.stackexchange.com/help).
  • I could just give people the database schema, but that only tells you so much. For example, if a value is an integer but it's an enumeration (1 means this, 2 means that, 3 means this other thing, etc), you can't get that from the schema alone. So I need to produce some documentation for the tables and columns in the database, which also provides me the opportunity to present the information in whatever organizational structure makes the most sense for our users.
  • My question is: are there best practices for going from a DB schema to documentation? If this were an API, for example, then in some languages I could write inline comments that could be automatically turned into reference documentation using tools like Javadoc or Doxygen. Is there something like that for DB schemas, or would I have to write my own transformation tools (which isn't worth the effort for the size of this project)? Or do people writing schemas just inspect the schema and write separate documentation? Are there conventions for doing this? I'm an experienced technical writer but I'm new to databases.
  • (In case it matters, I need to deliver HTML. This is a volunteer project (not actually open-source, but along those lines) and I have no budget for tools.)
#3: Attribution notice added by user avatar System‭ · 2019-12-08T03:40:52Z (almost 5 years ago)
Source: https://writers.stackexchange.com/q/12587
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by (deleted user) · 2019-12-08T03:40:52Z (almost 5 years ago)
I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look at what the database offers, and write their SQL queries. Think of something like [SEDE](http://data.stackexchange.com/help).

I could just give people the database schema, but that only tells you so much. For example, if a value is an integer but it's an enumeration (1 means this, 2 means that, 3 means this other thing, etc), you can't get that from the schema alone. So I need to produce some documentation for the tables and columns in the database, which also provides me the opportunity to present the information in whatever organizational structure makes the most sense for our users.

My question is: are there best practices for going from a DB schema to documentation? If this were an API, for example, then in some languages I could write inline comments that could be automatically turned into reference documentation using tools like Javadoc or Doxygen. Is there something like that for DB schemas, or would I have to write my own transformation tools (which isn't worth the effort for the size of this project)? Or do people writing schemas just inspect the schema and write separate documentation? Are there conventions for doing this? I'm an experienced technical writer but I'm new to databases.

(In case it matters, I need to deliver HTML. This is a volunteer project (not actually open-source, but along those lines) and I have no budget for tools.)

#1: Imported from external source by user avatar System‭ · 2014-08-10T18:59:39Z (about 10 years ago)
Original score: 9