Document the business rules

[joonas]

I think it would be a worthwhile effort to create a document somewhere that discusses the various "business rules" for the entities within Gittip.

Things like, what are the different states a participant can be in. Which type of participants can receive payments, etc.

Any thoughts?

[chadwhitacre]

Does this make sense as comments and docstrings in code?

[joonas]

I think it would be better if it was gathered in to a single place, in a document form maybe?

I find it sometimes hard to follow/remember these things when they are scattered across the codebase.

[chadwhitacre]

@joonas Best practice with docs in Python is to auto-generate them from code using Sphinx. Would that help?

[chadwhitacre]

'Cause then they'd be gathered together into a single place and would be scattered across the codebase.

[joonas]

@joonas Best practice with docs in Python is to auto-generate them from code using Sphinx. Would that help?
'Cause then they'd be gathered together into a single place and would be scattered across the codebase.

I suppose that would work too, I would just like to see them in one place outside of code as well so that no-one has to hunt around for them

[chadwhitacre]

If we do this right we'll get business rules as well as API all in one place. Let's consider hosting on ReadTheDocs.org since they're big on Gittip and it'd be nice to cement the relationship.

[zbynekwinkler]

http://gittip.readthedocs.org/en/latest/ has been started and has a separate issue #1312. Shall we make a label for developer documentation to connect all the issues?

[zbynekwinkler]

I think the way to go with this is to encode this into the self checks #1705. That way the documentation is a code that is run all the time and therefore does not get out of date. I am in favor in closing this and go ahead with the self checks. If anyone agrees with me, please close this issue.

[zbynekwinkler]

Ok, let's do it the other way around. If someone disagrees, please reopen the issue. 😉

[chadwhitacre]

Good call, @zwn. Per #1977, let's try to encode business rule documentation in docstrings on the self-checks and expose it on building.gittip.com.

[zbynekwinkler]

👍