Re: Bead Docs etc.

[Alex Harui]

To automatically solve that problem, we could try to teach the asdoc emitter to 
try to sniff out the tag in a createElement method.  But otherwise, we could 
add a new ASDoc tag that describes that is injected into the DOM.

My 2 cents,
-Alex

On 7/19/18, 10:36 AM, "Harbs"  wrote:

I think they were looking for “select”. They were trying to use 
intellisense (in VS Code) to find it.

I’m not sure how to solve that problem.


> On Jul 19, 2018, at 8:29 PM, Alex Harui  wrote:
> 
> Ask them where they would have looked for the answers.  IMO, having smart 
searching in ASDoc would have helped.  Type in "dropdown" and see all classes 
with "dropdown" in the name.  Type in "disable" see all classes with "disable" 
in the name.  Could they work on improving the ASDoc app?
> 
> -Alex
> 
> On 7/19/18, 10:20 AM, "Harbs" mailto:harbs.li...@gmail.com>> wrote:
> 
>Problems they’ve run into today:
> 
>Finding a dropdown component.
> 
>Figuring out DisableBead and how to fade (DisabledAlphaBead).
> 
>> Also keep in mind that ASDoc is an app for Royale so we can add more 
asdoc tags and filter and do other visualizations on those tags.
> 
>Yes. I was wondering something along these lines.
> 
>> On Jul 19, 2018, at 8:16 PM, Alex Harui  wrote:
>> 
>> I'm not sure how it can be "self-documenting". Beads can be re-used by 
any strand.  Sometimes it will work, sometimes it won't.  There is no way for 
the bead author to list all strands it is known to work on, nor is the a way 
for a strand to list all beads that will work with it.  You can write up a list 
of what you know at the time, but it will get stale and require lots of energy 
to maintain.  I have the same concern for a list in our docs as well.  I think 
it will get stale and not describe the full range of possibilities.
>> 
>> I feel like you didn't really state the fundamental question.  What 
problem are they actually running into?  IOW, are they really looking for a 
list of assumptions or invariants a bead has?  That might be describable at 
author time.  Could it be discovered by the compiler so that is 
self-documenting?  Not sure about that.  We could list the interface 
dependencies or something like that.
>> 
>> Many folks write code by trial-and-error, and beads were meant to be 
easy to add and remove.  Try it, oops, it doesn't work, try another one.
>> 
>> Also keep in mind that ASDoc is an app for Royale so we can add more 
asdoc tags and filter and do other visualizations on those tags.
>> 
>> My 2 cents,
>> -Alex
>> 
>> On 7/19/18, 5:03 AM, "Harbs" mailto:harbs.li...@gmail.com> >> wrote:
>> 
>>   Well, duh. I forgot about the royal-docs repo… 😳
>> 
>>   They can just fork that and submit pull requests.
>> 
>>   I do think that we should have some of this self documenting from the 
source code though. I’d like to explore that.
>> 
>>   Thanks!
>>   Harbs
>> 
>>> On Jul 19, 2018, at 2:23 PM, Andrew Wetmore mailto:cottag...@gmail.com>> wrote:
>>> 
>>> Starting a page in the docs project and putting together material would 
be
>>> great. Then we can link it into the published docs when it is ready. I 
am
>>> not sure who grants permissions/access for that.
>>> 
>>> a
>>> 
>>> On Thu, Jul 19, 2018 at 8:14 AM, Harbs mailto:harbs.li...@gmail.com>> wrote:
>>> 
 I just started some folks (my daughter and some friends) on some Royale
 work. They’re still getting into things. Hopefully as they get more 
into
 things, they will be able to contribute.
 
 One of the big things they are struggling with is discovering what
 components there are and what bead can work with which components. If 
I was
 not here to help them, it would be almost impossible to get going. One 
of
 them expressed interest in helping writing documentation for this as 
they
 are learning.
 
 What’s the best way for her to do that? It doesn’t really fit into the
 wiki. I’m not sure how to give her access to the docs.
 
 I think ideally, this should be something that the code self-documents.
 
 Thoughts?
 
 Harbs
>>> 
>>> 
>>> 
>>> 
>>> -- 
>>> Andrew Wetmore
>>> 
>>> 
https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cc52ab38bd9d248dd52b608d5ed6f94d4%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C1%7C636675985850576041&sdata=ECkPC4lmBreJPnEMhIKIMbJApeHy1eATT5vzoPYkXS8%3D&reserved=0
 

Re: Bead Docs etc.

[Harbs]

I think they were looking for “select”. They were trying to use intellisense 
(in VS Code) to find it.

I’m not sure how to solve that problem.


> On Jul 19, 2018, at 8:29 PM, Alex Harui  wrote:
> 
> Ask them where they would have looked for the answers.  IMO, having smart 
> searching in ASDoc would have helped.  Type in "dropdown" and see all classes 
> with "dropdown" in the name.  Type in "disable" see all classes with 
> "disable" in the name.  Could they work on improving the ASDoc app?
> 
> -Alex
> 
> On 7/19/18, 10:20 AM, "Harbs"  > wrote:
> 
>Problems they’ve run into today:
> 
>Finding a dropdown component.
> 
>Figuring out DisableBead and how to fade (DisabledAlphaBead).
> 
>> Also keep in mind that ASDoc is an app for Royale so we can add more asdoc 
>> tags and filter and do other visualizations on those tags.
> 
>Yes. I was wondering something along these lines.
> 
>> On Jul 19, 2018, at 8:16 PM, Alex Harui  wrote:
>> 
>> I'm not sure how it can be "self-documenting". Beads can be re-used by any 
>> strand.  Sometimes it will work, sometimes it won't.  There is no way for 
>> the bead author to list all strands it is known to work on, nor is the a way 
>> for a strand to list all beads that will work with it.  You can write up a 
>> list of what you know at the time, but it will get stale and require lots of 
>> energy to maintain.  I have the same concern for a list in our docs as well. 
>>  I think it will get stale and not describe the full range of possibilities.
>> 
>> I feel like you didn't really state the fundamental question.  What problem 
>> are they actually running into?  IOW, are they really looking for a list of 
>> assumptions or invariants a bead has?  That might be describable at author 
>> time.  Could it be discovered by the compiler so that is self-documenting?  
>> Not sure about that.  We could list the interface dependencies or something 
>> like that.
>> 
>> Many folks write code by trial-and-error, and beads were meant to be easy to 
>> add and remove.  Try it, oops, it doesn't work, try another one.
>> 
>> Also keep in mind that ASDoc is an app for Royale so we can add more asdoc 
>> tags and filter and do other visualizations on those tags.
>> 
>> My 2 cents,
>> -Alex
>> 
>> On 7/19/18, 5:03 AM, "Harbs" >  > >> wrote:
>> 
>>   Well, duh. I forgot about the royal-docs repo… 😳
>> 
>>   They can just fork that and submit pull requests.
>> 
>>   I do think that we should have some of this self documenting from the 
>> source code though. I’d like to explore that.
>> 
>>   Thanks!
>>   Harbs
>> 
>>> On Jul 19, 2018, at 2:23 PM, Andrew Wetmore >> > wrote:
>>> 
>>> Starting a page in the docs project and putting together material would be
>>> great. Then we can link it into the published docs when it is ready. I am
>>> not sure who grants permissions/access for that.
>>> 
>>> a
>>> 
>>> On Thu, Jul 19, 2018 at 8:14 AM, Harbs >> > wrote:
>>> 
 I just started some folks (my daughter and some friends) on some Royale
 work. They’re still getting into things. Hopefully as they get more into
 things, they will be able to contribute.
 
 One of the big things they are struggling with is discovering what
 components there are and what bead can work with which components. If I was
 not here to help them, it would be almost impossible to get going. One of
 them expressed interest in helping writing documentation for this as they
 are learning.
 
 What’s the best way for her to do that? It doesn’t really fit into the
 wiki. I’m not sure how to give her access to the docs.
 
 I think ideally, this should be something that the code self-documents.
 
 Thoughts?
 
 Harbs
>>> 
>>> 
>>> 
>>> 
>>> -- 
>>> Andrew Wetmore
>>> 
>>> https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cc52ab38bd9d248dd52b608d5ed6f94d4%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C1%7C636675985850576041&sdata=ECkPC4lmBreJPnEMhIKIMbJApeHy1eATT5vzoPYkXS8%3D&reserved=0
>>>  
>>> >>  
>>> 

Re: Bead Docs etc.

[Alex Harui]

Ask them where they would have looked for the answers.  IMO, having smart 
searching in ASDoc would have helped.  Type in "dropdown" and see all classes 
with "dropdown" in the name.  Type in "disable" see all classes with "disable" 
in the name.  Could they work on improving the ASDoc app?

-Alex

On 7/19/18, 10:20 AM, "Harbs"  wrote:

Problems they’ve run into today:

Finding a dropdown component.

Figuring out DisableBead and how to fade (DisabledAlphaBead).

> Also keep in mind that ASDoc is an app for Royale so we can add more 
asdoc tags and filter and do other visualizations on those tags.

Yes. I was wondering something along these lines.

> On Jul 19, 2018, at 8:16 PM, Alex Harui  wrote:
> 
> I'm not sure how it can be "self-documenting". Beads can be re-used by 
any strand.  Sometimes it will work, sometimes it won't.  There is no way for 
the bead author to list all strands it is known to work on, nor is the a way 
for a strand to list all beads that will work with it.  You can write up a list 
of what you know at the time, but it will get stale and require lots of energy 
to maintain.  I have the same concern for a list in our docs as well.  I think 
it will get stale and not describe the full range of possibilities.
> 
> I feel like you didn't really state the fundamental question.  What 
problem are they actually running into?  IOW, are they really looking for a 
list of assumptions or invariants a bead has?  That might be describable at 
author time.  Could it be discovered by the compiler so that is 
self-documenting?  Not sure about that.  We could list the interface 
dependencies or something like that.
> 
> Many folks write code by trial-and-error, and beads were meant to be easy 
to add and remove.  Try it, oops, it doesn't work, try another one.
> 
> Also keep in mind that ASDoc is an app for Royale so we can add more 
asdoc tags and filter and do other visualizations on those tags.
> 
> My 2 cents,
> -Alex
> 
> On 7/19/18, 5:03 AM, "Harbs" mailto:harbs.li...@gmail.com>> wrote:
> 
>Well, duh. I forgot about the royal-docs repo… 😳
> 
>They can just fork that and submit pull requests.
> 
>I do think that we should have some of this self documenting from the 
source code though. I’d like to explore that.
> 
>Thanks!
>Harbs
> 
>> On Jul 19, 2018, at 2:23 PM, Andrew Wetmore  wrote:
>> 
>> Starting a page in the docs project and putting together material would 
be
>> great. Then we can link it into the published docs when it is ready. I am
>> not sure who grants permissions/access for that.
>> 
>> a
>> 
>> On Thu, Jul 19, 2018 at 8:14 AM, Harbs  wrote:
>> 
>>> I just started some folks (my daughter and some friends) on some Royale
>>> work. They’re still getting into things. Hopefully as they get more into
>>> things, they will be able to contribute.
>>> 
>>> One of the big things they are struggling with is discovering what
>>> components there are and what bead can work with which components. If I 
was
>>> not here to help them, it would be almost impossible to get going. One 
of
>>> them expressed interest in helping writing documentation for this as 
they
>>> are learning.
>>> 
>>> What’s the best way for her to do that? It doesn’t really fit into the
>>> wiki. I’m not sure how to give her access to the docs.
>>> 
>>> I think ideally, this should be something that the code self-documents.
>>> 
>>> Thoughts?
>>> 
>>> Harbs
>> 
>> 
>> 
>> 
>> -- 
>> Andrew Wetmore
>> 
>> 
https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cc52ab38bd9d248dd52b608d5ed6f94d4%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C1%7C636675985850576041&sdata=ECkPC4lmBreJPnEMhIKIMbJApeHy1eATT5vzoPYkXS8%3D&reserved=0
 

Re: Bead Docs etc.

[Harbs]

Problems they’ve run into today:

Finding a dropdown component.

Figuring out DisableBead and how to fade (DisabledAlphaBead).

> Also keep in mind that ASDoc is an app for Royale so we can add more asdoc 
> tags and filter and do other visualizations on those tags.

Yes. I was wondering something along these lines.

> On Jul 19, 2018, at 8:16 PM, Alex Harui  wrote:
> 
> I'm not sure how it can be "self-documenting". Beads can be re-used by any 
> strand.  Sometimes it will work, sometimes it won't.  There is no way for the 
> bead author to list all strands it is known to work on, nor is the a way for 
> a strand to list all beads that will work with it.  You can write up a list 
> of what you know at the time, but it will get stale and require lots of 
> energy to maintain.  I have the same concern for a list in our docs as well.  
> I think it will get stale and not describe the full range of possibilities.
> 
> I feel like you didn't really state the fundamental question.  What problem 
> are they actually running into?  IOW, are they really looking for a list of 
> assumptions or invariants a bead has?  That might be describable at author 
> time.  Could it be discovered by the compiler so that is self-documenting?  
> Not sure about that.  We could list the interface dependencies or something 
> like that.
> 
> Many folks write code by trial-and-error, and beads were meant to be easy to 
> add and remove.  Try it, oops, it doesn't work, try another one.
> 
> Also keep in mind that ASDoc is an app for Royale so we can add more asdoc 
> tags and filter and do other visualizations on those tags.
> 
> My 2 cents,
> -Alex
> 
> On 7/19/18, 5:03 AM, "Harbs"  > wrote:
> 
>Well, duh. I forgot about the royal-docs repo… 😳
> 
>They can just fork that and submit pull requests.
> 
>I do think that we should have some of this self documenting from the 
> source code though. I’d like to explore that.
> 
>Thanks!
>Harbs
> 
>> On Jul 19, 2018, at 2:23 PM, Andrew Wetmore  wrote:
>> 
>> Starting a page in the docs project and putting together material would be
>> great. Then we can link it into the published docs when it is ready. I am
>> not sure who grants permissions/access for that.
>> 
>> a
>> 
>> On Thu, Jul 19, 2018 at 8:14 AM, Harbs  wrote:
>> 
>>> I just started some folks (my daughter and some friends) on some Royale
>>> work. They’re still getting into things. Hopefully as they get more into
>>> things, they will be able to contribute.
>>> 
>>> One of the big things they are struggling with is discovering what
>>> components there are and what bead can work with which components. If I was
>>> not here to help them, it would be almost impossible to get going. One of
>>> them expressed interest in helping writing documentation for this as they
>>> are learning.
>>> 
>>> What’s the best way for her to do that? It doesn’t really fit into the
>>> wiki. I’m not sure how to give her access to the docs.
>>> 
>>> I think ideally, this should be something that the code self-documents.
>>> 
>>> Thoughts?
>>> 
>>> Harbs
>> 
>> 
>> 
>> 
>> -- 
>> Andrew Wetmore
>> 
>> https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cc52ab38bd9d248dd52b608d5ed6f94d4%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C1%7C636675985850576041&sdata=ECkPC4lmBreJPnEMhIKIMbJApeHy1eATT5vzoPYkXS8%3D&reserved=0
>>  
>> 

Re: Bead Docs etc.

[Alex Harui]

I'm not sure how it can be "self-documenting". Beads can be re-used by any 
strand.  Sometimes it will work, sometimes it won't.  There is no way for the 
bead author to list all strands it is known to work on, nor is the a way for a 
strand to list all beads that will work with it.  You can write up a list of 
what you know at the time, but it will get stale and require lots of energy to 
maintain.  I have the same concern for a list in our docs as well.  I think it 
will get stale and not describe the full range of possibilities.

I feel like you didn't really state the fundamental question.  What problem are 
they actually running into?  IOW, are they really looking for a list of 
assumptions or invariants a bead has?  That might be describable at author 
time.  Could it be discovered by the compiler so that is self-documenting?  Not 
sure about that.  We could list the interface dependencies or something like 
that.

Many folks write code by trial-and-error, and beads were meant to be easy to 
add and remove.  Try it, oops, it doesn't work, try another one.

Also keep in mind that ASDoc is an app for Royale so we can add more asdoc tags 
and filter and do other visualizations on those tags.

My 2 cents,
-Alex

On 7/19/18, 5:03 AM, "Harbs"  wrote:

Well, duh. I forgot about the royal-docs repo… 😳

They can just fork that and submit pull requests.

I do think that we should have some of this self documenting from the 
source code though. I’d like to explore that.

Thanks!
Harbs

> On Jul 19, 2018, at 2:23 PM, Andrew Wetmore  wrote:
> 
> Starting a page in the docs project and putting together material would be
> great. Then we can link it into the published docs when it is ready. I am
> not sure who grants permissions/access for that.
> 
> a
> 
> On Thu, Jul 19, 2018 at 8:14 AM, Harbs  wrote:
> 
>> I just started some folks (my daughter and some friends) on some Royale
>> work. They’re still getting into things. Hopefully as they get more into
>> things, they will be able to contribute.
>> 
>> One of the big things they are struggling with is discovering what
>> components there are and what bead can work with which components. If I 
was
>> not here to help them, it would be almost impossible to get going. One of
>> them expressed interest in helping writing documentation for this as they
>> are learning.
>> 
>> What’s the best way for her to do that? It doesn’t really fit into the
>> wiki. I’m not sure how to give her access to the docs.
>> 
>> I think ideally, this should be something that the code self-documents.
>> 
>> Thoughts?
>> 
>> Harbs
> 
> 
> 
> 
> -- 
> Andrew Wetmore
> 
> 
https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cc52ab38bd9d248dd52b608d5ed6f94d4%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C1%7C636675985850576041&sdata=ECkPC4lmBreJPnEMhIKIMbJApeHy1eATT5vzoPYkXS8%3D&reserved=0

Re: Bead Docs etc.

[Harbs]

Well, duh. I forgot about the royal-docs repo… 😳

They can just fork that and submit pull requests.

I do think that we should have some of this self documenting from the source 
code though. I’d like to explore that.

Thanks!
Harbs

> On Jul 19, 2018, at 2:23 PM, Andrew Wetmore  wrote:
> 
> Starting a page in the docs project and putting together material would be
> great. Then we can link it into the published docs when it is ready. I am
> not sure who grants permissions/access for that.
> 
> a
> 
> On Thu, Jul 19, 2018 at 8:14 AM, Harbs  wrote:
> 
>> I just started some folks (my daughter and some friends) on some Royale
>> work. They’re still getting into things. Hopefully as they get more into
>> things, they will be able to contribute.
>> 
>> One of the big things they are struggling with is discovering what
>> components there are and what bead can work with which components. If I was
>> not here to help them, it would be almost impossible to get going. One of
>> them expressed interest in helping writing documentation for this as they
>> are learning.
>> 
>> What’s the best way for her to do that? It doesn’t really fit into the
>> wiki. I’m not sure how to give her access to the docs.
>> 
>> I think ideally, this should be something that the code self-documents.
>> 
>> Thoughts?
>> 
>> Harbs
> 
> 
> 
> 
> -- 
> Andrew Wetmore
> 
> http://cottage14.blogspot.com/

Re: Bead Docs etc.

[Andrew Wetmore]

Starting a page in the docs project and putting together material would be
great. Then we can link it into the published docs when it is ready. I am
not sure who grants permissions/access for that.

a

On Thu, Jul 19, 2018 at 8:14 AM, Harbs  wrote:

> I just started some folks (my daughter and some friends) on some Royale
> work. They’re still getting into things. Hopefully as they get more into
> things, they will be able to contribute.
>
> One of the big things they are struggling with is discovering what
> components there are and what bead can work with which components. If I was
> not here to help them, it would be almost impossible to get going. One of
> them expressed interest in helping writing documentation for this as they
> are learning.
>
> What’s the best way for her to do that? It doesn’t really fit into the
> wiki. I’m not sure how to give her access to the docs.
>
> I think ideally, this should be something that the code self-documents.
>
> Thoughts?
>
> Harbs




-- 
Andrew Wetmore

http://cottage14.blogspot.com/

Bead Docs etc.

[Harbs]

I just started some folks (my daughter and some friends) on some Royale work. 
They’re still getting into things. Hopefully as they get more into things, they 
will be able to contribute.

One of the big things they are struggling with is discovering what components 
there are and what bead can work with which components. If I was not here to 
help them, it would be almost impossible to get going. One of them expressed 
interest in helping writing documentation for this as they are learning.

What’s the best way for her to do that? It doesn’t really fit into the wiki. 
I’m not sure how to give her access to the docs.

I think ideally, this should be something that the code self-documents.

Thoughts?

Harbs