search

EEXCESS / eexcess

This is the EEXCESS main repository bringing togehter the different sub-projects and providing the documentation in the Wiki. Its the starting point when you want to know more about the project.
http://eexcess.eu/
5 stars 2 forks source link

Suggestion for improvement of documentation #9

Open chseifert opened 8 years ago

chseifert commented 8 years ago

I was trying to set up a minimal example for a recommendation request to the privacy proxy solely on the basis of the documentation. This did not work out as planned ;-)

It would be helpful to indicate the difference between the request to the federated recommender and to the privacy proxy at the beginning of the page https://github.com/EEXCESS/eexcess/wiki/%5B21.09.2015%5D-Request-and-Response-format

ThomasCerq commented 8 years ago

I tried to improve the documentation here: https://github.com/EEXCESS/eexcess/wiki/%5B21.09.2015%5D-Request-and-Response-format#pp-query-format Do you think it would be helpful to highlight the differences between both formats even before the first one is presented? Moreover it's not that simple to explain, as there are multiple formats (PP-QF1 and PP-QF2 instead of just FR-QF for instance). PP-QF1 = FR-QF + attribute Origin, whereas PP-QF2 is more complicated to explain. Don't get me wrong, if it needs to be done, I will do it ;-)

chseifert commented 8 years ago

I am not sure myself. The most important use case for the documentation is for novices which do not know anything about EEXCESS. With the recent changes, "I" know now, that I should always query the PP. But next comes the FR-QF. What if we simply change the order of the query formats. (PP first, then FR?) And add a link at the beginning to my try of a Quick Start Guide? https://github.com/EEXCESS/eexcess/wiki/Getting-Started-Guide-for-Client-Developers

I am thinking now, that we can not "explain everything on every page". But have to have more overview pages, instead.

ThomasCerq commented 8 years ago

"PP first, then FR" > Yes it could be the solution. From an external point of view, as well as from a conceptual point of view, it makes more sense to introduce the format for the PP first.

I think the Quick Start Guide should give the overview you mentioned. I should explain the workflow (where the query goes) and what the query is made of (i.e., format). I can help with it if you want.

chseifert commented 8 years ago

For the client developer perspective it is imho not important to know where the query goes (after all the PP is just a proxy). And from a privacy-perspective we want nobody to call the FR directly. So we just remove it from the user's mental model ;-) and view [PP+FR+{PR}] as one retrieval system.

This just came to my mind when thinking on how to write the quick start guide - and with all the format explanations it is already quite long.

I'd rather add a section on "how to ensure privacy" - explaining the settings for the privacy proxy and logging.

What do you think?

mgrani commented 8 years ago

Sounds very good. I would also add a section/page on "The querying process in detail" in order to explain the overall querying process. From this the roles of PP, FR and PR should become clear for those people, who want to dig into more details.

ThomasCerq commented 8 years ago

I think you're right Christin. The quick start guide should present the system as a black box (that's how Gerhard et al. see it) in which the PP is the only entry point.