Request for documentation review

packages
1

Last week I updated documentation for socialize:friendships and I’ve just finished updating the documentation for socialize:base-model. To make sure that the documentation is fully usable I would like to request that others take a look and make sure that the documentation covers everything needed to use the packages. Thanks in advance.

2 Likes
2

Just taking a glance at the docs for friendships, it doesn’t really give me what I want - it just starts right off with API documentation for requests. It doesn’t tell me how friendships are modeled, what features there are, any code samples, reasons I should use this package, etc. I would suggest starting with a simple introduction describing the use cases for this package and a simple example for getting started. Then once I am familiar with the basics I would want to read complete docs for all of the classes and methods. I would also highly suggest adding a table of contents if possible.

5 Likes
3

Awesome, great points. Thanks @sashko for taking the time to actually take a look and give feedback.

1 Like
4

I found the API documentation to be fairly straightforward, and to have gotten right to the important parts. It’s definitely heading in the right direction.

Sacha is right: more discussion of how the friendships are modeled would definitely help. Maybe even a small flow chart or diagram? For instance, the docs don’t seem to mention socialize:user-model and social:user-profile, which are actually rather important pieces.

Just as a bit of background: I’m working with a few different groups on Social Health Records… MedBook, Biolog, Gopher, CareWatch… there’s at least four of them we’re working on. We’re looking seriously at using the socialize:friendships framework, but have some healthcare specific use cases that require transitive closure over a friendship graph (i.e. a guardian approving a friendship for a child and elderly dependent; hierarchical organizations where a manager might approve a friendship for members of a group; etc). So, we’re evaluating how socialize:friendhips might work with alanning:roles and medbook:collaborations.

I recently did a big refactor of medbook:collaborations and wound up with the clinical:collaborations package, which has some methods that are really begging to have a proper User class. And it just so happens that socialize:user-model provides that. So, we’re on the verge of adding socialize:user-model as a dependency.

The way the profile is modeled, however, makes a few assumptions about firstName, lastName, and so forth. That’s a fairly traditional approach; but a more internationalized approach uses familyName, givenName, nickName, fullName. So, that’s a thing.

And there’s the bigger architectural change in that the find() and findOne() methods return a class instance, rather than a JSON object. We’re not necessarily against that approach; but it will have a ripple effect across all of our applications and require rewrites among all of them. So that’s also a thing. (In fact, it’s probably the elephant in the room, regarding adoption of the socialize:friendships subsystem.)

All in all, though, it’s very well thought out; very clean code; clear documentation. It’s definitely on people’s radar, and I’m personally counting my blessings that you’ve put so much work into it.

1 Like
5

Thanks @awatson1978. I’m very excited to see the things people use the packages for and thus am grateful for the feedback so that I may improve them and their documentation so they may be utilized to their fullest.

I really thought that the extension of socialize:user-model was pretty well outlined… I guess I’ll have to see about come clarification on that front. socialize:user-profile though isn’t mentioned because while it is one of the many pieces that can be added together to create an app, it’s not explicitly included unless the developer chooses to add it.

As far as the packages go, they are made to be very extensible. All of the classes can have new methods added, their schema’s extended to accommodate new fields on their collections and allow rules added so to allow for cases where you may want to allow functionality that wasn’t part of the package as it was built. Allow rules were chosen specifically as apposed to deny so that additional checks could be added for things such as roles.

To touch on assumptions of socialize:user-profile, it really doesn’t make any assumptions and is just a base on which to build. The firstName and lastName in the documentation are just there as an example of how you might use the package.

As it stands the schema has 4 keys as follows:

  • userId
  • username (optional)
  • createdAt (autoValue, only set on insert)
  • lastUpdated (autoValue, set and updated on ever update)

This allows you to then add your own additional field definitions to the schema via the appendSchema method.

Profile.appendSchema({
    'givenName': {
        type: String,
        max: 30,
    },
    'familyName': {
        type: String,
        max: 40,
    }
});

//and now since we have the new fields and we might want to combine them, how about a helper?
Profile.methods({
    'fullName': function() {
        return this.givenName + " " + this.familyName;
    }
})

I will admit that the Class based nature of the package set can be an issue if you have a code base that is not structured in this way. I find however that this is such a powerful feature. By using this method it’s allowed me to clean up my code significantly as well as move 90% of my helpers out of my templates and into my models where they can be reused anywhere an instance is returned from a query.

If anyone else wants to help on the package set please do… As far as integrating the packages if anyone needs any help, I’m just an email or message away.

Thanks for the kind words Abigail, hopefully I can get the documentation perfected over the next few weeks.

1 Like
6

The individual packages are each well documented (including socialize:user-model). It’s the relationship between them and the big-picture that’s a bit murky.

And the User class is what ties everything together; so its the center of it all. When somebody is considering integrating socialize:friendships into their app, the User class is likely to be the biggest architectural change they’ll have to contend with. (There’s lots of reason to move to your approach. It’s not a question of ‘why’. It’s simply a matter of ‘how’. Something along the lines of a refactor/upgrade path would be extremely useful.)

A flow chart or diagram would definately help people visualize what’s going on.

Also, I’m hoping to release an early version of the social health record demo by the end of next week.

2 Likes