HTML Documentation looks like Javadoc :-)

This is probably not easy task or fast to resolve, but take it as open discussion and lets see what comes from it.

In these days of cool looking engines VP produced content still looks like plain old javadoc. Its simple as it.

There are multiple aspects which I will target one by one with some example of how it might look more attractive:

  • Navigation
    There should be something similar like the Model explorer tree view and interactive search (I write, it automatically filters)
  • Graphical layout
    One of the very nice example of how to produce high quality docs is read-the-docs.
  • Support of code highlight, custom pages (non-diagram), etc.
    Maybe markdown language support will be good, source code highlighting.
  • Doc composer
    When I click generate data documentation on logical diagram context menu, what comes out looks like this:

    I don’t know, but this is not how documentation might looks :slight_smile:

Overall it feels like I am still 10-15 years back when browsing HTML docs… :slight_smile: Maybe its just my own feeling, let me know what you think in general and maybe we can discuss here future look of the docs.

What other thinks?

2 Likes

About the Doc. Composer of ERD Data Specification.

Sorry for the bad design on the document. It is showing ERD.image + Entities.name/column/pk/fk/etc…


BTW, the semi-colon after “Master Entities” is missing. We will fix it.

This content is generated by ERD’s hidden template Data Specification - Loop.
You may customize the document by deleting the generated content of Entities,
and use another template(s) to generate what you want. As screenshot:

PS:
On your screenshot, the font-size of Foreign Keys, Master Entities are bigger than other text.
It may be a bug on hidpi. We will check it.

@peter.wong - no need to sorry, again VP is great product and there is lot of work visible behind it.

But even when I publish the project into HTML form (via Publish project button), the cascade styles feels like from many years back…

I am just saying this that you can take a look how modern documentation frameworks looks like. I talk about CCS.

Some samples:
Slack API

https://www.mkdocs.org/
GitHub - slatedocs/slate: Beautiful static documentation for your API

And one example for all is Atom.io documentation:
https://electronjs.org/

In these days when you do Data Governance its not just about table modeling, but documenting whole analytical process. Defining standards, documenting model to model mapping, etc. One inovative way of thinking in this space is done by Alation Data Catalog Products | Alation, again what this product produces and manages is quite impressive. Still their product doesn’t focus on full Data Governance management.

These are again just my thoughts for possible direction of VP evolution. Cover more data governance area. Make “really” beautiful docs.

Hope my words are not offensive to you.

Again thanks for VP.

Ladislav

I am very much in agreement with this post. It’s great to push a button and get instant documentation but I always have to edit the result so much that it’s not very much of a time savings over just building from scratch.
I would be very happy to have improvement in the ability to create my own templates. Since a few versions ago, the template engine changed and now requires online acces to the repository, I’ve never been able to get that to work.

Just my two cents. The diagramming and modeling capabilities are top notch. My colleagues are always very impressed with my diagrams and I would love to be able to easier create full documentation which would be even more impressive.

Bob

2 Likes