Document Your Data

Data Documentation with Bit.io

At bit.io we strive to make data easy to share and explore. A key part of that is providing context, and good documentation is the best to do that. Good documentation allows your users to understand what your data means, how it was gathered, and transforms raw data into meaningful information.

Viewing Documentation

In order to view or edit documentation for your database, click the button at the top of the table navigation view in the Data tab.

In the documentation section you can navigate, read, and edit (if you have permissions) all of the database's documentation.

👍

Pro Tip

You can query the table you're viewing documentation on by clicking the table icon on the right of the table header.

Editing Documentation

You can click on the pen in the upper right of any section (or double click the section) to edit the documentation for that section. All fields accept and render markdown except columns, which will always render plain text only.

To save your edits click the check mark in the upper right of the box, and to cancel hit the 'X'.

As mentioned above, all of your documentation is stored in the actual database via Postgres' COMMENT feature. This means that you can also edit the documentation via SQL commands, such as COMMENT on table table_name is 'This is a table';. Edits made via SQL may take a few seconds to be reflected in the documentation UI.

👍

Pro Tip

For faster editing, you can use ⌘-Enter on Mac or Ctrl-Enter on windows to save your edits. Escape to cancel

🚧

Style Risks

Since most of our documentation fields allow markdown, you have a lot of control over the look and feel of your documentation.

One thing to be cautious of is disrupting the hierarchical flow of you docs. This means you should avoid having larger text in the doc field for your tables than for your database and generally be attempt to be consistent in your styling.

This public database is a great example of well-formatted documentation.