write a contrib doc about the database

[chadwhitacre]

This info has traditionally lived in the README. Do we keep install instructions there? I'm thinking we should have bare-bones "quick start" in the README and write more substantial docs under /for/contributors/.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[chadwhitacre]

cf. https://botbot.me/freenode/gittip/msg/4892425/

[cakey]

I would keep any information directly related to installing or configuring in the README. That's where I personally expect it to be. Extra information such as code style, pull request etiquette etc can live at /for/contributors.

[tshepang]

me agrees with @cakey

[mvdkleijn]

Just a note here: even though I don't have the time to dig into aspen and python and gittip core code, I may have time to work on these docs. I'll definitely have time to review them thoroughly should someone else decide to pick it up.

Regarding /for/contributors... how about we add an abbreviated install and config guide in there, with a clear pointer to the readme for full details. That would give contributors at least a sense of the complexity etc without having to go to multiple sources.

[seanlinsley]

As far as having such documentation on the website, I'd suggest it be written in something like markdown that can be displayed in both contexts easily, except on the website it'd have custom CSS.

If those docs went in /docs and they were automatically added to the website itself at build-time, we'd have the best of both worlds.

[zbynekwinkler]

I don't think such documentation belongs to the main website. I'd just point potential contributors to the github repo and went from there. I'd also suggest to simplify simlify simplify. But we'll get there with the /about/ rework. There is a maintenance cost to everything we have and with such a small team I don't think we can afford it.

[chadwhitacre]

Copying over from #1413:

@zwn: @whit537 I've had some more time to think about it. How much do we want to keep the data in the db normalized and calculate most of things at display time? I must say that I lean in the direction of doing the most work at write time and in the show time just display what is in the db. I have some experience with google appengine and it almost forces you to do it this way by the api design. It leads to fairly scalable applications (we could avoid problems like #1417). However, from looking at the code you are in the other team, right?

I'd be tempted to make the dollars giving/receiving a column in the participant table and update it either at payday or at tip changing time.

@mvdkleijn: @zwn @whit537 If I may chime in here. I would respectfully suggest that you shouldn't be in either camp. Look at the data and look at how often it is pulled / requested.

If a user requests it only once, just calculate it at that time. If a user requests certain data often, store it and recalculate only if and when it changes. That will get you the most bang for your buck as it were. The likes of Google et all have so many users that is almost always cheaper to cache or store calculated values. I do still think that early optimization is a killer.

Note: in this case I'd store the (at payday) calculated result and update the stored result when people change how much they give (or take from a team). You can use payday to "recalibrate" as it were.

[chadwhitacre]

Had a Hangout w/ @zwn and @wyze on this (#1502). Hopefully that gets posted to YouTube. :-(

[chadwhitacre]

It posted! http://www.youtube.com/watch?v=DQIBkY77IHc 💃

[mvdkleijn]

According to #1296 this should be /about/helping not /for/contributors. If so, I suggest it'd be its own page.. something like /about/helping/database-information

[zbynekwinkler]

To reiterate my #1272 (comment) I don't think this belongs to the main site. I prefer the doc subdirectory in the repo (as is already started).

[mvdkleijn]

Then we need a decision to make this final. If we're going for a doc subdirectory, this ticket should be closed.

[mattbk]

Some database stuff exists at http://gratipay.readthedocs.io/.

[chadwhitacre]

Yeah, I'm fine to close.