New section about "Data Model"

[mnapoli]

#22

The guide "All about analytics data" has been split and extended into a new section with smaller articles:

As shown above, the database guides are still separated.

@mattab

[tsteur]

I'm not sure "Data Model" is the best name for what it actually contains. Maybe we can find a name related to "Workflow". Eg "Analytics Data Flow" or so

[mnapoli]

I understand, I'm not really fond of "Data Model" too, but the idea of the section is to fill the gap between the UI part and the database part.

Personally that part was a big black hole for me (especially because of archive data, log data, reports, records, metrics, …). I finally got to understand all the model of Piwik (in the MVC meaning), previously the article was "All about analytics data" and that title really didn't meant a lot to me. I interpreted "analytics" as end-user, not actual code. I think "Workflow" alone would be too fuzzy. So I want to make it clear to readers that this section is about the actual business logic of Piwik and the data model involved.

Maybe simply "Model"? "Core Model"? "Data Model & Workflow"? I like having Model because even though it's an overused and quite fuzzy term, it speaks a lot to a vast majority in developers (thanks to MVC): it's the part between Controllers/APIs and the database.

[mnapoli]

Maybe a better explanation: I'm trying to find guide titles that speak to a person that doesn't know the content of the guide, to help readers to have a global view of the docs (and Piwik itself) and to help them find the answer to their questions.

So sometimes I put a title that is not the best name for the actual content, but it's the name people will (hopefully) expect when looking for it. So when I read "All About Analytics Data" I was like "wtf is analytics data, is it a specific kind of data in Piwik? or in analytics in general? I want to know about Piwik's model classes/data model" (hence the current name).

[tsteur]

I think "All About Analytics Data" is a better name here especially when they don't know about Piwik.
"Data Model" doesn't have a lot of meaning and it is not really clear, and it does not really contain a "Data Model" does it? Not sure. At least it also contains many different things. And it is only about the Analytics Data part.

I didn't mean "Workflow" on its own. Only something related to "Workflow", or "Data Analytics". Eg "Data Analytics Workflow" or something else. Probably it could even just go under "Understanding Piwik".

The more I think about it, the better I like "All About Analytics Data". I assume @diosmosis came up with this name, maybe you have an idea?

[mnapoli]

From experience I can tell you that "All About Analytics Data" didn't mean anything to me (as a Piwik noob looking to understand what is the model part).

Titles should be addressed to PHP developers that don't know about Piwik. MVC is simple, it's a pattern we can find in every application, and everybody is used to it.

"Analytics Data" might seem obvious to Piwik developers, but I can tell you I had no idea what it meant, even though I've been using GA for many years and Piwik for ~ 5 months. What's worse, we are talking about the category title. If you look at actual guide titles it's even worse (log data, archive data, archiving process, …). That's the reason why I wanted to make it clear to reader that all those articles in that section are about the Model part of Piwik: to counterbalance the "wtf-ness" of the sub-titles.

[tsteur]

I'm just saying "Data Model" is not really any better and technically maybe even wrong IMO. I would actually expect to see Data Models but I think there isn't. And it contains information about the Archiving Process and how it is done in PHP etc which I meant with it contains different things. Maybe not the name is confusing but what it contains.

Maybe it makes sense to rename "Log data" to "Raw data" or "Raw tracking data" and "Archiving data" to "Aggregating data". In those articles we can explain the term "archiving" etc. This might give developers also a better idea what to expect there.

In the end it is probably not really worth making a big fuss about it as this section is unimportant anyway. Maybe it makes sense to move those articles under a "Advanced understanding of Piwik" part etc. The idea of the platform is to hide all this complexity and only provide "simple" APIs for plugin developers to achieve things. The part we are talking about is rather important for Core developers or for the few people that are really interested in understanding how Piwik works. For most plugin developers, who maybe just want to rename/hide a Menu item, create a new report, track new data it is not important. The part that is maybe useful for them is already explained under "How Piwik works".

Under this aspect I would even reorganise the menu within Develop but that's another issue. Eg. Controllers / Views / Pages are listed as one of the first entries but our goal is that they ideally don't have to use it unless they actually want to build a custom page such as our "Help" page. One of the first entries should be "Tracking custom data" or "Custom Reports" or ... which explains how to create a dimension, how to create a report, how to create a widget, etc. The next use case might be "Changing Piwik's UI" or so which contains articles like Menus, JavaScript/CSS, ... I presume this rather goes to #22

[mattab]

Let's have a quick meeting sometime next days or next week to discuss the developer guides menu structure, prior to the blog post in matomo-org/matomo#7154

[mattab]

nice changes, it's much easier to follow this way

[mattab]

Feedback:

• maybe http://developer.piwik.org/guides/archive-data could be renamed "Report data" as the archive is more an implementation detail.
• and the page http://developer.piwik.org/guides/reports could be merged into "Report data" ?
  • having less doc about this makes sense with simplify archiving logic by implementing archiving layer as caching backend matomo#7126 where the goal will be to remove some archiver complexity