Continuing the discussion from Workaround for missing FHIR attributes that OpenMRS requires:
@surangak, clearly, we don’t have things documented in an accessible way. Any suggestions for where these behaviors could have been documented that would have led you to read them, rather than just try it out in the demo?
I think in my case, the biggest problem was that I needed to check in two places. I looked at the db schema, and then had to compare it with the validator, which turned out to be different. Is it common to see differences between the two validators? and also, not sure how to best document this - I mean, it wont do well as a separate wiki page etc.
Perhaps better error codes / messages that indicate where the error originates from?
You really should look at the validators in code, rather than the db
schema. (At least in theory the validators should replicate any db
validations.) I agree that a separate wiki page would never be kept
up-to-date. Maybe publishing the javadocs more publicly?
I would not want error messages in the UI to indicate where in the code
they originate from – the end user shouldn’t be seeing that detail. Or
were you suggesting something else?
More publicly than api.openmrs.org?
I will admit that I have literally never gone to api.openmrs.org of my own
I meant, should we publicize them more, and link to them from wiki pages,
answers, talk, etc. E.g. if someone asks “is cause of death required?” we
could point them to the api docs for PatientValidator.validate()
Agree. I’m also guilty of this same crime. I agree with Darius, at least one of the ways to solve this problem would be to adopt a mindset that actively encourages our devs to point people to our api docs, and encourage its use. Other than that, i’m afraid we don’t have many options
If it’s an end user you can’t point him/her to the api docs, but to the wiki instead. Ideally all the business rules should be documented in the wiki. And while in the patient CRUD pressing F1 should go directly to the wiki page (contextual help).
Also, if the business rule does not satisfy everyone then it could be parameterized and dynamically executed depending on the configuration. For instance, a customer may want that death cause is mandatory and another the contrary, in this cause the DB should allow nulls (the less restrictive case).
One thing I’ve suggested in the past, but never got to doing is the maven site. I think it encourages people to document the code better because its generated by maven from source, compared to a wiki, because you have to go to another place to do it.
+1 to having documentation be auto-generated from code comments.
I too fear that (manually) regularly updating a wiki page describing the
behavior of code is unrealistic given the resources in the community.
@zakaria_amine & @wyclif - any comments about how this might be improved along with the work in this year’s GSoC project for REST documentation?
I am not sure if this is relevant to what we are doing at the moment.
If someone is not willing to spend half an hour documenting something in the wiki I doubt he will spend the same time putting that in the code (with annotations or whatever). Also in the code you cannot add diagrams, pictures etc.
I can definitely say that personally, for myself, I will document things in
the code in the file that I’m actively editing, that I wouldn’t spend the
time to go to a separate wiki page to review.