Documentation - best practice discussion

OpenEMR Development
1

tmccormi wrote on Tuesday, July 30, 2013:

We need to try and make Documentation, both User and Developer related, a natural part of the process of OpenEMR community. In the past I have paid for a tech writer to update the users guide with each release and that is fine, but it can only go so far. The phpDoc blocks goes a long way toward, eventually, having good coding docs but needs to be enforced for all new contributions, which is a bit of a burden, but still necessary.

We could use a lot more code reviewers, Brady is a Bulwark but needs help, obviously Kevin, Rod and I don’t spend much time on that (wish I could).

At OSCON I was given this link by Andy Oram of O’Reilly Publishing that is interesting:

http://www.praxagora.com/andyo/professional/reliable.html

At the Community Leadership Conference that preceded OSCON, I went to a session on this topic that included developers from LibreOffice, Mozilla, Ubuntu and more and had a wide ranging discussion about it. Making sure that people that want to contribute documentation are welcomed and given “developer” like privileges to the code base was one key to success.

An idea I had, which I think we could do easily, was to require developers submitting new/updated code to be required to note as to whether the change requires a update to Documentation and what type: User, Schema, Architecture, Technical, etc … This info would be required to get code committed. I would not require that the documentation be updated, just noted that it was needed so someone could, later, find the things that need docs and do them. I think the best place for that may be in a the code itself, but that would require the code to be updated after the doc is done… maybe an new tracker type instead?

Thoughts & Ideas?

Tony
President OEMR

2

tmccormi wrote on Friday, August 02, 2013:

crickets chirping… I see documentation is as exciting to our community as it is in the rest of the Open Source world.
-Tony

3

yehster wrote on Friday, August 02, 2013:

Everyone would benefit from better documentation and I support your suggestion in principle, but I suspect that forcing documentation as a requirement for commits is more likely to act as a disincentive for contributing code rather than encouragement to create documentation.

4

tmccormi wrote on Friday, August 02, 2013:

The point is that I’m NOT enforcing documentation at commit, I’m suggesting that the contributor just indicate whether existing documentation needs to be updated. That’s all.
–Tony

5

yehster wrote on Friday, August 02, 2013:

What does the contributor use to indicate that need?

6

bradymiller wrote on Saturday, August 03, 2013:

Hi,

We do now enforce standard code documentation on new commits:
http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly#Examples_for_OpenEMR

There are several “live” wiki documents that should get updated with the codebase, which we should direct developers to modify (I have been doing this intermittently):

  1. New Database Tables:
    http://www.open-emr.org/wiki/index.php/OpenEMR_System_Architecture#Database
  2. New Options (ie. Globals):
    http://www.open-emr.org/wiki/index.php/Administration_Globals
  3. New User Specific Options:
    http://www.open-emr.org/wiki/index.php/User_Settings
  4. New Lists:
    http://www.open-emr.org/wiki/index.php/Administration_Lists
  5. New ACOs:
    http://www.open-emr.org/wiki/index.php/Adding_and_Removing_User_Permissions

Probably makes sense for somebody to place this listing in a section in the How to Document OpenEMR code wiki page:
http://www.open-emr.org/wiki/index.php/How_to_Document_Your_Code_Properly#Examples_for_OpenEMR
(hint: I am not going to do this for you; Start using the wiki… :slight_smile: )

Then we have a place to direct developers when they should be updated the “live” wiki docs.

And for new features, we should at least get developers to make a “stub” type wiki instruction page with specifics on how to use(but does not need to be user friendly or fancy, just the minimum). Then at least the new feature is documented and not “lost” and somebody can always improve on the documentation in the future. These types of documents are perfect grounds for contributors that just want to help with documentation.

-brady
OpenEMR

7

tmccormi wrote on Sunday, August 04, 2013:

While we do (sort of) enforce technical documentation, it’s the user side that I am mostly concerned about.

As to where to indicate that user doc is needed, that was the key question I asked in the first post.

I think the best place for that may be in a the code itself, but that would require the code to be updated after the doc is done… maybe an new tracker type instead?

Tony

8

blankev wrote on Sunday, August 04, 2013:

Let me make it clear, I have sometimes ideas, but I AM NOT A PROGRAMMER!

Most programmers are advised, just to find back what they did and when they did it, some kind of info is included in most pieces of software when they make or change a programm.
At least that is the impression of this USER.

Would the following be possible:

with modern techniques get the rough stuff of every file into some kind of WIKI-page (all supported by the idea of what Brady did achieve with the Translation page.)

  1. A name of the piece of software,
  2. Date of changes made,
  3. Intention of what was to be achieved.
  4. Some extras, would be nice but sometimes this is not even needed.

Than some dummies in programming like me, might have the courage to make pages out of the received information. This than can be included into the WIKI-manual for the latest Version-update. Once there is some piece of written text it is usually just a matter of reshuffle and sometimes it even can include some extras for a first time USER to make it understandable and usable.

THOUGHTS?

  1. Documentation of every patch could receive some purpose dedicated info the rough way and could follow the OpenEMR directory files for implementation.

  2. Every new version, need to have some major update information corrected to show the right info for the USERS, and another manual for the Developers.

(I was thinking of something like adding an extra characters and accompanying text after: //pimmiq or *pimmiq to start with the Initials/PrivateCode of the programmer to differentiate. Import and send to the right spot in the rough manual, to be changed in due time or can be deleted if not used or if outdated.)

9

fsgl wrote on Sunday, August 04, 2013:

While it is perfectly reasonable to have “rules of the road” for code documentation, care must be taken not to discourage user documentation.

Despite the warning on the bottom of each page about merciless editing and promiscuous propagation of the article, it appears that the opposite is true. One can almost see cobwebs forming above some Wiki articles. The article about the Dispensary is quite long in the tooth and really needs a make-over.

Brady has been a prodigious writer on both fronts. He probably would like to have an army of secretaries and coders, but that takes money.

Documentation on the user side should remain informal to encourage pro bono participation. If there are errors, anyone with an account can edit to their heart’s content. It seems to work fine for Wikipedia.

10

yehster wrote on Friday, August 09, 2013:

I’ve mentioned it before and I don’t know if it’s even possible with the sourceforge forums, is the ability to have “sticky threads” where we can informally document and track things.

11

fsgl wrote on Friday, August 09, 2013:

Please ask SourceForge Support. They are very timely and helpful in their replies.

If Allura has provisions for sticky posts, then the next step is petitioning El Jefe.

Google is still better than the resident search engine, therefore stickies will be a great asset.

12

yehster wrote on Friday, August 09, 2013:

https://sourceforge.net/p/allura/discussion/?source=navbar
Funny, allura doesn’t use their own system for discussion… Hmmm…

13

fsgl wrote on Saturday, August 10, 2013:

Not a lot of traffic with 50 posts in toto. Perhaps easier to use email instead.

There’s a “Request an enhancement” link, bottom left hand corner, if it escaped attention

14

fsgl wrote on Wednesday, September 11, 2013:

The “Request an enhancement” link is basically a wish list, so it is better to just email SourceForge Support directly.

Here is the reply:

"If a project member wanted to make a topic sticky, they could use the pencil icon in the upper right when viewing a thread.

Regards,
Chris Tsai
SourceForge Support"

El Jefe,

After the dust settles, is it possible to have the pencil icon? It would make the troops happy. No ticket number was assigned to the email. While I am in the petitioning mode, how about the Delete button as well? The Delete button would be helpful to extricate oneself from embarassing situations.

15

htuckjr wrote on Monday, September 16, 2013:

Speaking of pro bono participation, I contribute user docs because 1) OpenEMR is a very worthwhile project and I feel good about myself for helping out, 2) I’m getting experience in an important part of my new Health Informatics career, and 3) I get bragging rights among my peers that I’m doing something very cool.

What are some motivators for the OpenEMR code contributors? Recognition? I notice that the businesses offering commercial support to the Project have a link to their business advertisements right there on the very front page of the wiki. The importance to the Project of community volunteerism is acknowledged, but the the volunteers/ contributors are not recognized like the businesses are. I see the ‘Acknowledgements’ page but it’s not prominent- I had to go looking for it- and it’s not recognition oriented.

You know the old saw about eliciting desired behavior: “give them a reputation to live up to”. Is there some report that might be automated and placed on a wiki page, like “Contributors of N-thousand lines of Quality Code” which they were only eligible for if their code was well commented? Whoever evaluates the code for commit to the codebase would just make a note somewhere to count the lines of that contribution for the Quality Code page, and the report would take care of the details.

If it’s decided that such a thing is a good idea and somebody would set up the report and tell me how to run it I would commit to maintaining that page on a monthly basis for the next year.

I’d offer to code the report but I only know perl, Commodore Basic and Access VBA. Could probably re- learn COBOL if necessary.

16

bradymiller wrote on Monday, September 16, 2013:

Hi,

From a developer/reviewer standpoint, it’s very difficult to track code contributions in a meaningful manner(in both quality and quantity).

The “OpenEMR Professional Support” page is actually a project to attempt to:

  1. Allow commercial entities mechanism to advertise their services in a unbiased and fair manner.
  2. Get more contributions from the commercial side of things (The “Certified OpenEMR Contributors” recognition)
    See here for the Talk page on making entries etc. for more info on that:
    http://www.open-emr.org/wiki/index.php/Talk:OpenEMR_Professional_Support

The “Acknowledgements” page is what is used for the “Acknowledgments, Licensing and Certification” link on the main OpenEMR login page. All contributors on this page are basically treated the same. As with attempting to track code contributions it is even tougher to do this with all the other types of contributions (translations, testing, documentation, forum support, hard cash, Pimm(gets his own category :slight_smile: ) etc.).

Regarding Commodore Basic, I still remember typing in Basic programs into my TRS-80 (http://www.ebay.com/itm/Radio-Shack-TRS-80-Color-Computer-Ext-Basic-1-1-1982-Modified-to-64K-WORKS-/130989209000)…

-brady
OpenEMR

17

fsgl wrote on Monday, September 16, 2013:

To the above aphorism, one could say: A measure of a man can be taken from the quality of his work.

The Acknowledgment page is very democractically structured without distinction as to the quality or quantity of each contributor’s work. Brady has been rather gracious in inviting additions to that page. Almost anyone can have their name listed.

We may want to avoid McDonald’s marquee, “One Zillion Hamburgers Sold”.

Some of us would prefer to go about contributing with as little fanfare as possible; even incognito, but then Brady would not grant an account.

It is hardly surprising that an old timer would argue for the status quo.

Yes, Pimm is sui generis and we value him for it.

18

blankev wrote on Monday, September 16, 2013:

Now after these two above comments it might be, I have to do a re-write of the Acknowledgement page. Or can we add another part where other Acknowledged partners can leave their comment…

19

htuckjr wrote on Monday, September 16, 2013:

Of course, if the remedy had been as simple a fix as I suggested, it would have happened already. I do know that if OpenEMR solves this problem there are a couple other projects out there that will want to know how it’s done!

Actually my very first computer was a Timex Sinclair 1000 from which I upgraded to the C=64 because Compute! magazine had all those code listings for interesting software. I attribute the beginning of my eyesight deterioration to the weeks I spent typing in those columns and pages of numbers just to get their SpeedScript word processor. Ahh, those were the days.