More documentation

README.md

@@ -1,13 +1,13 @@
 # Socialite
-## A social-network app made with Meteor
+## A simple facebook-like app made with Meteor
 
-Here come Socialite. It implements classic features from facebook-like networks, including:
+Here come Socialite. It implements classic features from facebook-like social networks, including:
 - Profile
 - Pictures
 - Friends
-- Messenging system
+- Messaging system
 
-It is mostly a prototype and has little out-of-the-box features. It is meant to be extended and tuned to fit one's need. This project is mostly for my own amusement, and because I wanted to play with the [Meteor](http://meteor.com) platform.
+It is mostly a prototype. This project is mostly for my own amusement, and because I wanted to play with the [Meteor](http://meteor.com) platform.
 
 ## How to run
 
@@ -16,89 +16,95 @@ It is mostly a prototype and has little out-of-the-box features. It is meant to
 
 Should do it. It should download all dependencies then initialize the database.
 
-You can tweak the fixture file to add/remove questions/fake users. Also copy the main.config.sample file to main.config.js and edit what you want.
+You can tweak the fixture file to add/remove questions/fake users (default fake users all reside in Hong Kong). Also copy the main.config.sample file to main.config.js and edit what you want.
 
 ## Cool stuff
 
-The questions for users' profile are stored in the database, with different type, custom template and validation. When a user update its profile, its inputs are checked against the question database and their validation. This ensure an easy and somehow secure way to administrate and render what is generally consider (at least by me) as a horrible pain in the neck.
+The questions for users' profiles are stored in the database, with different custom template and validations. When a user update its profile, its inputs are checked against the question database and their validations. This ensure an easy and somehow secure way to administrate and render what is generally consider (at least by me) as a horrible pain in the neck.
 
 It's all in Meteor, so everything is pretty much instantaneous, which is cool.
 
-There should be some i18n support, but a lot of placeholders are missing (and some string are hardcoded), and the lexicon is far from being complete. The logic is here though.
+There should be some i18n support, but a lot of placeholders are missing (and some string are hardcoded), plus the lexicon is far from being complete. The logic is here though, and should allow for on-the-fly change of language, assuming more than one language should be made available.
 
 ## TODO
 
 There is a lot left to do and little time. Among the list:
-- The setting page for user is pretty much non-existent
-- There is a commenting system, but it is not plugged anywhere, so it is pretty useless
+- The setting page for user is pretty much non-existent.
+- There is a commenting system, but it is not plugged anywhere.
 - With more questions we could have a cool Profile Editing page.
 - Would be cool to be able to like/+1 users' content and action.
 - Add more user interactions, it's a bit dry right at the moment.
 - Some design. Current one is pretty minimalist. The UI in general is pretty much only what [Boostrap](https://github.com/twitter/bootstrap) offers.
 - Security might not be horrible, but it is certainly not good. User input are validated but not sanitized at the moment.
+- I would love to write unit test for it, be it only to stabilize the API, but TDD with Meteor doesn't seem to be mature enough at the moment and I only found trivial case of testing.
 
 ## API
 
-API is a big word, but here are a few of the useful helpers/methods implemented in Socialite.
+API is a big word, but here are a few of the useful publications/collections/helpers/methods implemented in Socialite.
 
 ### Publications
 
 #### myData
 
 The current user data: full profile, settings and if the profile is completed (to be able to display the profile creation flow otherwise).
 
-On-ready, sets the `settings` and `profileComplete` Session variable. to indicate that 1. the profile is loaded and allow for easy access of those information.
+On-ready, sets the `settings` and `profileComplete` Session variable. to indicate that 1. the profile is loaded and 2. allow for easy access of those information.
 
 #### myPictures
 
 All the current user Photos.
 
 #### myNotification
 
-Notification for the current user, with potential related users (if the notification is "friend request from A", we also publish a light version of A's information, to display with the notification.
+Notification for the current user, with potential related users (from Meteor.users -- if the notification is "friend request from A", we also publish a light version of A's information, to display along the notification.
 
 #### myFriendlist
 
-All my friends (from Friends) and the related users information (Meteor.users.
+All my friends (from Friends) and the related users information (from Meteor.users).
 
 #### myNews
 
-Information happening to me and my interactions with other users (from Activities).
+Information happening to me and my interactions with other users (from Activities and Meteor.users).
 
 #### myConversations
 
 The list of my current conversations with people, friend or not (from Conversations) and their info (from Meteor.users).
 
 #### questions
 
-The list of questions.
+The list of questions (from Questions).
 
 #### oneConversation
 
 Depends on the Session variable `currentConversation`. Get some of the messages (from Messages) for a given conversation.
 
 #### userProfile
 
-Depends on the Session variable `currentUserProfile` (set when visiting a user profile). Publish user information from Meteor.users.
+Depends on the Session variable `currentUserProfile` (set when visiting a user profile). Publish user information from Meteor.users. What is published can be configured in `Meteor.users.privateProfileInformation` and `Meteor.users.myProfileInformation` (config file).
 
 #### oneUserPicture
 
-Publish pictures (from Photos) for the user set in `currentUserProfile`. TODO: merge with `userProfile`.
+Publish pictures (from Photos) for the user set in `currentUserProfile`.
 
 #### oneUserActivities
 
-Publish activities for a given user (from `currentUserProfile`). TODO: merge with `userProfile`.
+Publish activities for a given user (from `currentUserProfile`).
 
 #### searchResults
 
-Publish a list of users (from Meteor.users) matching a search query. On-ready, set the `searchQueryDone` Session variable, for client side update of the template.
+Publish a list of users (from Meteor.users) matching a search query. On-ready, set the `searchQueryDone` Session variable, to trigger client side update of the template.
+
 Publish related Presences objects to know the online status of users in the search results.
 
 ### Collections
 
 #### Meteor.users
 
-The default Meteor.users collection, with nit much change. The profile information are stored in the `profile` field of a user document.
+The default Meteor.users collection, with not much change. The profile information are stored in the `profile` field of a user document. Additional used fields are:
+- `loc`: stores the Mongo 2d geographical coordinates of a user, if available
+- `visible`: indicates that the user can be seen/browsed by other users.
+- `profile_complete`: indicates that the user finished the registration process and provide enough information to be left roaming freely on the website.
+- `cooldown`: potential cooldown penalty for user posting messages too fast (for spam prevention).
 
 #### Activities
 
@@ -183,7 +189,7 @@ Remove a friendship between two users, both ways (A to B AND B to A). Just make
 
 Send the message `document.body` to user whose `_id` is `document.to`. A couple thing happens there. We first check that the sender is allowed to communicate with the target, and also compute a velocity score, to prevent people from sending message too fast (aiming at preventing automatic spamming).
 
-The velocity/cooldown algorithm is quite trivial. Users are allowed to send X message per period of Y seconds (can be tuned in the `main.config.js` file). If they send faster than that, they get a penalty of Z seconds (again, can be configured). If they try again, they add Z second to the current penalty. An automatic spammer not throttling down it's sending rate will then automatically blocked itself for hours or days.
+The velocity/cooldown algorithm is quite trivial. Users are allowed to send X message per period of Y seconds (can be tuned in the `main.config.js` file). If they send faster than that, they get a penalty of Z seconds (again, can be configured). If they try again, they add Z second to the current penalty. An automatic spammer not throttling down its sending rate will then automatically blocked itself for hours or days.
 
 #### uploadPhoto(options)
 
@@ -197,6 +203,16 @@ Record that the current user is connected to the website. If the user is visible
 
 If `invisible`, stop broadcasting the user online status to his connections, otherwise keep broadcasting.
 
+## (Not So) FAQ
+
+### Does it scale?
+
+No idea. Does Meteor scale? If I/you run into a scaling issue, then success is at the door. Then I/you can invest time and money to ensure it scales.
+
+### Can it do X. Y or Z
+
+Probably not, but feel free to fork it.
+
 ## License stuff
 
 This project is licensed with the MIT license.