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" <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 <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 <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
