Suggestions for the Docs / Package

[Former Community Member]

Hi All - starting a thread, inspired by @iRomin, asking for input on the documentation as well as general package structure.

iRomin's suggestions so far :

  #1) suggestion on docs: 1) Explain architecture side by side with example code

  #2) Your examples are great -- push them in the docs explaining in detail.

  #3) Take a detailed collaborative example (co-browsing) - and explain building it by scratch.

  #4) Take a running example and show via screenshots what happens in the DevConsole (Nodes, Users, Items).

  #5) Host an online wiki site like an AFCS Recipe Site -- where Adobe and other users can submit recipes.

1) and 2) seem like things we should put in the Developer Guide - or should 2) go in the individual example folders?

3) and 4) seem like things that we could do screencasts for - I bought ScreenFlow, should start using it.

5) is a good idea - we'll look into what the labs wiki system can support.

  So, please post your own doc / package annoyances, things we should be making easier to find, or other structural issues with the SDK zip.

Message was edited by: Nigel Pegg (added call to action at the end)

[Former Community Member]

Suggestion from me : break out the "extras" folder, put 2 new top-level folders :

1. "Server Integration"
   
2. "Dev Tools"

1) will have all the "scripts" (plus more to come) directories, while 2) will have the Dev Console and the LocalConnection Server.

  Not sure how people "navigate" the SDK zip (there's an index.html but not sure people use it).

[Former Community Member]

Hi Nigel,

On #3: Take a detailed collaborative example and build it from scratch -- here is why I mentioned it.

I think what would be really nice is to take a couple of the cool applications that are present on the AFCS Showcase site and go through building it step by step. That would be really helpful.

In my little experience with AFCS so far (mainly as a developer interested in learning it) and with some interactions with a couple of friends -- here is a common theme:

a) We look at AFCS -- use the pods -- everything looks good.

b) Then we look at the AFCS Showcase site -- look at Sudocomo, the new Word game and co-browsing Flickr and we are like "How do we build that?". Is all the heavy lifting done by AFCS?

I think the key thing to illustrate somehow is that AFCS plays an important role in sharing state. Then what you do with that state is the functionality of the Client Application. I think its just a mindshift but I am seeing many developers fall into a trap where they are not able to reconstruct what role AFCS played in creating some of the showcase applications at a detailed level and what AFCS was not responsible for in those showcase applications.

I hope I am getting the point across.

Thanks

Romin Irani (iRomin)

romin.k.irani@gmail.com

[ConnectSolution]

These are all great suggestions.

After talking to a few developers and stumbling on this myself, I agree that there needs to be a better explanation of nodes and collectionNodes as to how they coincide with user roles and permissions. The idea of a side by side example with screen shots of the changes to the DevConsole seems like it would be useful.

[ukkpower]

I would agree with the previous posts about more a in depth explanation of the CollectionNodes.

From a Flex point of view I find the Cookbook and flex examples blogs invaluable.

[isa___]

Suggestion:

Adding a multi-language chat pod taking advantage of flash player 10 text engine.

[Former Community Member]

Well, that's not really a SDK structure or doc request =). We'd love to see something like this, but probably won't get to it any time soon - if you build one, let us know!

nigel

[richtextformat]

hey nigel (et al)

would like to see more detail in the docs. was just looking at this method for instance, in 'UserManager':

myUserRole

property

myUserRole:int  [read-only]

Specifies the current user's role.

This property can be used as the source for data binding.

Implementation
    public function get myUserRole():int

Very vague, leaves me wondering what the possible values for this could be and what they would mean. Are -5, 0, 3 and 2341234 valid values, what would a userRole of 2 indicate? this gives me no idea.

[richtextformat]

it may just be me too, but i am a huge fan of so-called 'idiot sheets', a disgusting term used to describe (and demean) documentation for people whom one assumes knows NOTHING about the thing they are trying to learn. step-by-step guides, covering EVERY detail. the format that always make it easiest for me to learn is a list of items, each item being a two-step thing where you say 'this is what you do' then 'this is why you do it'

the reason idiot sheets in this format is good is because you can CHOOSE to ignore whatever you want to - "oh, i understand UserDescriptors already, i can skip on", or "i don't care WHY this bit works, i'm just glad i know that i HAVE to do it and HOW" - but if you DO need to learn EVERYTHING its all there.

or, in short, idiot sheets are able to teach EVERYONE EVERYTHING in a single format.

[Former Community Member]

Thanks for the feedback!

nigel