mercredi 11 mars 2015

Database documentation consideration

There are many tools and professional tools to document the database.
But I would like the documentation to be as accessible and simple as possible... so avoid the usage of tool is best to offer an easy access to the information.

Regarding database documentation, here some nice recommendation collected on the Net
For my money, some good human-readable documentation (perhaps supplemented with diagrams of smaller portions of the system) will give you the most mileage. This will include, for each table:

* Descriptions of what the table means and how it's functionally used (in the UI, etc.)
* Descriptions of what each attribute means, if it isn't obvious
* Explanations of the relationships (foreign keys) from this table to others, and vice-versa
* Explanations of additional constraints and / or triggers
* Additional explanation of major views & procs that touch the table, if they're not well documented already

With all of the above, don't document for the sake of documenting - documentation that restates the obvious just gets in people's way. Instead, focus on the stuff that confused you at first, and spend a few minutes writing really clear, concise explanations. That'll help you think it through, and it'll massively help other developers who run into these tables for the first time.

Tooling or not tooling
One of the most recommended approach (after use of Tools) is to use the database feature allowing to include comment within the database schema.
If this is efficient and probably one of my favourite, this approach requires the user to know this feature to access the information.
The usage of tools also requires the user to have this tools prior to access the information.

So usage of tools is perhaps not the best approach for the audacious project which have to be open-source and KISS (keep is simple stupid) even for the technical documentation

Word processing document
Another approach than I used to document project is the usage of a word processing document.
I usually reverse engineering databases and maintain a Word documentation with database structure and all the useful information  about it.
The problem is that "Word" is a non-open-source tools! If I do use Libre-Office/Open-Office, the Windows user would have trouble to open-it.
An option would be to publish a PDF version on regular base... but that's not very efficient, and still include binary file (Word or Libre-Office) within the sources of Audacious project.

A Simple text base file
That would be definitively a good option. Not specific software needed, easily available, can be included within the source code.
As issue we have:
  • No document indexes
  • No images inclusion (sometime quite useful).
A Wiki?
A wiki is not my prefered approach. It requires to be stored somewhere on Internet and that someone pay for it. No money = No service = No wiki = No documentation.
If the documentation could be organized and modified more easily (and more nicely),  it would also been more difficult to consolidate the information to create a PDF/Word like document.

On the other hand, the "Audacious User Guide" should also been available... a Wiki is the best tool to build and organize such documentation/information.
So why not integrate developer (and database) documentation within the same wiki?

Any suggestion?
Any suggestion are welcome.

Aucun commentaire:

Enregistrer un commentaire