royale-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Harui <>
Subject Re: Bead Docs etc.
Date Thu, 19 Jul 2018 17:16:23 GMT
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,

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

View raw message