edits for introduction through channel-nodes

[julierhill]

Hi Simon,

I've been following the order of the API reference menu, starting with Introduction and getting through Channel-Nodes. I wanted to push what I've done so far to see what you think. For the most part, I've corrected grammatical errors (not that there were many), reduced wordiness in areas or tried to express an idea more directly. In a couple of areas, I've made more significant changes to content and/or organization. Below, I've briefly explain my thought process behind the more significant changes, as well as raise some questions that came up along the way:

Introduction: (Question) You mention the "BuddycloudID" many times, but it wasn't clear to me what this is or how it's different from a username. I assume it's an internal ID that the app assigns a user on the back end of things. Maybe just a quick explanation of it in the Authentication section.

Pagination: Query Parameters (Question) I didn't understand the "index" parameter.

Accounts:

• "using the mobile phone number": it isn't clear who is using the phone number (I imagine it's the user, but the first method indicated such while the second method doesn't)
• The username looks like it's in the form of an email, but then the Query Parameters table says that an email is optional. These seem to contradict each other.

Channels: I know we discussed this one at length a little while ago, but I've added just a few more changes to (in my opinion) more clearly illustrate the concept of channels and nodes, and explain how they work together. I used a very generic example (dog ownership), which might not be the best example to use. Maybe you can substitute an example that's more reflective of an actual Buddycloud channel.

I also mentioned the two types of channels in the beginning to make that clearer to reader earlier on, which made the second topic (Channel Types) slightly redundant. I decided to change the subheading to Personal Channels v. Topic Channels, as the table below really is a comparison of the two types. I also added a column called "traits" so the developer knows what aspects are being compared, though I wasn't positive about the terms I used in the trait column.

Channel-nodes: (Question) This question is the one I already emailed you about (a node called "posts").

I should be able to work on it during the evenings this week. The hard part was getting started and gaining the technical understanding I needed to be able to evaluate the documentation. Now I feel like I have a better handle on it and should be able to finish the rest of it soon. Please let me know if these changes have been helpful, or if I should be doing something differently.

Thanks!

[imaginator]

Thanks @jrbickford! Will edit in your other concerns now.

[imaginator]

I've been following the order of the API reference menu, starting with Introduction and getting through Channel-Nodes. I wanted to push what I've done so far to see what you think. For the most part, I've corrected grammatical errors (not that there were many), reduced wordiness in areas or tried to express an idea more directly. In a couple of areas, I've made more significant changes to content and/or organization. Below, I've briefly explain my thought process behind the more significant changes, as well as raise some questions that came up along the way:

Introduction: (Question) You mention the "BuddycloudID" many times, but it wasn't clear to me what this is or how it's different from a username. I assume it's an internal ID that the app assigns a user on the back end of things. Maybe just a quick explanation of it in the Authentication section.

Agreed - I've removed this and replaced with username since that's all it is.

Pagination: Query Parameters (Question) I didn't understand the "index" parameter.

@lloydwatkin "We don't use index so just remove it" - removed.

Accounts:

"using the mobile phone number": it isn't clear who is using the phone number (I imagine it's the user, but the first method indicated such while the second method doesn't)

Fixed - to make clearer now. (the username can just be a phone number)

The username looks like it's in the form of an email, but then the Query Parameters table says that an email is optional. These seem to contradict each other.

You can use an identifier that looks like an email address. I have added a note below the params section.

Channels: I know we discussed this one at length a little while ago, but I've added just a few more changes to (in my opinion) more clearly illustrate the concept of channels and nodes, and explain how they work together. I used a very generic example (dog ownership), which might not be the best example to use. Maybe you can substitute an example that's more reflective of an actual Buddycloud channel.

Seen that. Going to edit it a bit more - but good idea with the example.

I also mentioned the two types of channels in the beginning to make that clearer to reader earlier on, which made the second topic (Channel Types) slightly redundant. I decided to change the subheading to Personal Channels v. Topic Channels, as the table below really is a comparison of the two types. I also added a column called "traits" so the developer knows what aspects are being compared, though I wasn't positive about the terms I used in the trait column.

That is good. Makes it much clearer.

Channel-nodes: (Question) This question is the one I already emailed you about (a node called "posts").

Renamed to /social to make it clear.

I should be able to work on it during the evenings this week. The hard part was getting started and gaining the technical understanding I needed to be able to evaluate the documentation. Now I feel like I have a better handle on it and should be able to finish the rest of it soon. Please let me know if these changes have been helpful, or if I should be doing something differently.

Yay! Thanks Julie