Markdown Editor for Table and Column Notes

Hey all! One thing that I think gets overlooked is the value an ERD plays from the perspective of some specialized support roles. In my position I am tasked with

  1. Resolving Data Conflicts and Issues (Writing SQL)
  2. Creating Documentation for new Support Agents
  3. Reporting Defects to QA and our Development team and discovering where data may be invalid.

For this reason and many others, having an ERD with a software our size is extremely valuable for members in my organization from all departments. The feature I would like to propose however is a built in Mark Down editor, inside of dbdocs, OR dbdiagram. It can be intimidating at first learning SQL and understanding the complex schema of a lot of our DB, and utilizing the markdown support has allowed me to create some wonderful documentation.

However, markdown isn’t a universally known formatting language for a large number of people learning SQL on the job, and self study is sometimes not practical for a support agent who honestly might not benefit from learning on their own time. But, if this agent would like to add their findings about some of the joins, or someone who may already know SQL but doesn’t want to spend the time troubleshooting their Markdown Formatting when adding information about what different values mean in different fields. This information is incredibly useful to have, but extremely cumbersome to implement in any meaningful way, as documentation drives the development world and without being able to consult a million stack overflow threads about your own organizations schema, there is no other way to learn than from within.

As much as I have loved dbdiagram, dbdocs I believe is going to be huge in commercializing future features inside of both programs because of how much this functionality would extend itself to new and pre-exiting users who aren’t going to remember the 100s of JOINs in our DB in addition to the many states and descriptions.

Draw Backs of No Built In Mark Down Editor:

  • Difficult to create effective documentation
  • Greater barrier to entry to contribute
  • Takes more time to create documentation
  • Reduced the cost efficiency of using dbdiagram and dbdocs together in a large organization.

Good things about Built in MD editor

  • Easy to add to pre-existing documentation
  • No knowledge of markdown required
  • Time efficient to create documentation on large db schemas
  • Ability to create documentation that is effective and tailored to the general readers as well as proficient developers

Thank you for your detailed suggestion. We appreciate it.

We’ll consider implementing this in the future to make creating documentation flow more smoothly.


1 Like

I have the same issue as well. I thought of using this tool, imported my 300+ table MySQL structure, and then thought, let me add comments to my tables/columns, but alas! there’s no such way. The only way is to now edit the markdown. Crazy. That would be a lot difficult to do for so many tables. Initially, I thought, all I have to do is import and then inline WYSIWYG edit the notes/comments for tables, columns and ERs.

If it had this feature, I would be instantly sold to this tool.

1 Like

Update April 2024: This feature has been developed and released. Please see below for the official announcement.

Hope you guys like this feature.

1 Like