royale-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Wetmore <cottag...@gmail.com>
Subject Re: Proposed table of contents for Royale help documentation
Date Sat, 20 Jan 2018 00:31:54 GMT
It seems to me that there will be a period of heavy lifting as we populate
the help docs for the first time, and that then the load will diminish
significantly. I am happy to contemplate updating the ToC by hand a couple
of times a week indefinitely: small pain for big gain.

I would love to review the Flex stuff we inherited but never published. Can
you point me at it?

How much effort is involved in getting them to donate the rest? Everything
will have to be rebranded for Royale, of course; and probably a lot of it
is of limited use. But if it's a gift horse, why not?

a

On Fri, Jan 19, 2018 at 8:24 PM, Alex Harui <aharui@adobe.com.invalid>
wrote:

> I've been wondering if it was worth trying to autogenerate the TOC or not.
>  The only advantage is that it would allow us to add a page and have it
> appear without having to also edit the template.  I think I'll give up on
> auto-generating the TOC.
>
> BTW, in 2015, Adobe donated some Flex doc to Apache.  I don't remember
> what was in it, but Apache Flex never got around to publishing it.  It is
> sitting in a branch on our site repo.  There appears to be other Adobe doc
> still on Adobe's site that was not donated that deals with the basics of
> using MXML and AS3.  I'm not sure if we want to try to get that donated to
> Apache or not.  We can't use the content from the Adobe site directly.
>
> -Alex
>
> On 1/19/18, 4:12 PM, "Andrew Wetmore" <cottage14@gmail.com> wrote:
>
> >I feel like we are trying to fit ourselves to the limitations of a
> >template, rather than setting up to do what will present the material in
> >the best way. I am almost positive that we will have collections of pages
> >that we can't even anticipate now, but for sure "Flex in a Week" is a
> >great
> >example. (I would love to have that one back!)
> >
> >What is the virtue of an auto-generated table of contents? We are not
> >auto-generating the contents...
> >
> >On Fri, Jan 19, 2018 at 8:08 PM, Alex Harui <aharui@adobe.com.invalid>
> >wrote:
> >
> >> I've spent the afternoon reading Jekyll doc.
> >>
> >> Jekyll has a concept of "Collections" that could be used to help
> >> auto-generate a TOC, but if there is a "Welcome" collection (and a "Get
> >> Started" and "Create An Application" and other collections for each
> >> top-level), the collection pages will be at URLs like
> >> "apache.github.io/royale-docs/welcome/index.html.  There does not seem
> >>to
> >> be a way to have the landing page (when you hit the URL
> >> apache.github.io/royale-docs) be welcome/index.html.  Unless we put an
> >> redirect in index.html.
> >>
> >> Now we could make the Welcome not a collection and just a set of
> >>"pages".
> >> But I'm wondering if we are going to have any other "set" of
> >>documentation
> >> served from royale-docs such that the index.html should have a link to
> >>the
> >> Welcome collection as our main user document and some other set of
> >> pages/collections on royals-docs would be considered a different set
> >>with
> >> a different link from index.html.  If we generated static ASDoc would we
> >> stick it all on royale-docs?  There once was a whole series of tutorials
> >> like "Flex In A Week".  Would that be another "set"?
> >>
> >> Thoughts?
> >> -Alex
> >>
> >> On 1/19/18, 1:00 PM, "Andrew Wetmore" <cottage14@gmail.com> wrote:
> >>
> >> >>I assume that the Welcome page is the main index.html landing page?
> >>Maybe
> >> >on its content it will lead you more towards the Get Started page.
> >> >
> >> >Yes and yes.
> >> >
> >> >On Fri, Jan 19, 2018 at 4:40 PM, Alex Harui <aharui@adobe.com.invalid>
> >> >wrote:
> >> >
> >> >> OK, we'll leave it as you have it and see what kind of feedback we
> >>get.
> >> >> I
> >> >> assume that the Welcome page is the main index.html landing page?
> >>Maybe
> >> >>on
> >> >> its content it will lead you more towards the Get Started page.
> >> >>
> >> >> -Alex
> >> >>
> >> >> On 1/19/18, 9:36 AM, "Andrew Wetmore" <cottage14@gmail.com> wrote:
> >> >>
> >> >> >I am not sure I agree about putting "Getting Started" first. If
the
> >> >>table
> >> >> >of contents as I propose it appears with its top-level entries
> >> >>collapsed,
> >> >> >then "Get started" is the second item the reader sees. I do not
> >>think
> >> >>that
> >> >> >is too big of a hurdle to jump over.
> >> >> >
> >> >> >On Fri, Jan 19, 2018 at 1:19 PM, Alex Harui
> >><aharui@adobe.com.invalid>
> >> >> >wrote:
> >> >> >
> >> >> >> Hi Andrew,
> >> >> >>
> >> >> >> Thanks for doing this.  I'm wondering if we should have a
"Getting
> >> >> >> Started" before "Features and Concepts".  I would like to
see us
> >> >> >>emphasize
> >> >> >> the Express components more going forward, which may reduce
the
> >> >>emphasis
> >> >> >> on PAYG for the newbie.  PAYG is important to the framework
> >> >>developers
> >> >> >>in
> >> >> >> order to provide the app developer with more ways to tune
their
> >>app,
> >> >>but
> >> >> >> only if they need it.  I'd like to see the doc lead you to
> >> >>downloading
> >> >> >> Royale and getting some app up and running in, say, 10 minutes.
> >> >> >>
> >> >> >> I hope to spend some time on the doc over the next few days
or
> >>more,
> >> >>so
> >> >> >>I
> >> >> >> will keep this proposal in mind as we explore how to implement
the
> >> >>doc.
> >> >> >>
> >> >> >> Thanks,
> >> >> >> -Alex
> >> >> >>
> >> >> >> On 1/19/18, 7:38 AM, "Andrew Wetmore" <cottage14@gmail.com>
> wrote:
> >> >> >>
> >> >> >> >Hi, all:
> >> >> >> >
> >> >> >> >I have started to outline the sort of table of contents
for
> >>Royale
> >> >>user
> >> >> >> >documentation that I as a non-expert developer would want
to
> >>see. I
> >> >> >>would
> >> >> >> >want the ToC to lead me to information that will help
me both
> >> >>migrate
> >> >> >> >existing Flex projects to Royale and create new projects
within
> >>the
> >> >> >>Royale
> >> >> >> >ecosystem.
> >> >> >> >
> >> >> >> >The outline is in this Google Doc:
> >> >> >> >https://na01.safelinks.protection.outlook.com/?url=
> >> >> >> https%3A%2F%2Fdocs.goog
> >> >> >> >le.com%2Fdocument%2Fd%2F1ap0jzhqfhKITE3F_tFijndz_
> >> >> >> gpCKXgcZHlnycNSeTGw%2Fedi
> >> >> >> >t%3Fusp%3Dsharing&data=02%7C01%7Caharui%40adobe.com%
> >> >> >> 7C1861f488d46a4134ce4f
> >> >> >> >08d55f52a21a%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> >> >> >> 7C6365197308688271
> >> >> >>
> >>>31&sdata=3BswQuSRfgKvk7rZX83CXTRJsFhA7SEDWSlFQHkLIrM%3D&reserved=0
> >> >> >> >
> >> >> >> >If you use that link you should have editor privileges
for the
> >> >> >>document.
> >> >> >> >
> >> >> >> >I am fairly confident about the contents of the first
column. I
> >>have
> >> >> >>not
> >> >> >> >completed building out the second and third columns, but
I think
> >>you
> >> >> >>can
> >> >> >> >get a sense of what you might see as you drill down into
the help
> >> >>docs.
> >> >> >> >
> >> >> >> >I am really good at organizing this sort of stuff and
at helping
> >> >> >>explain
> >> >> >> >complex concepts clearly. However, I probably have the
least
> >> >>technical
> >> >> >> >knowledge of anybody reading this thread, so my role must
be in
> >> >>support
> >> >> >> >rather than as a first-level knowledge source.
> >> >> >> >
> >> >> >> >I will continue building out the second and third columns,
but
> >>feel
> >> >> >>free
> >> >> >> >to
> >> >> >> >pitch in. If you want to suggest things rather than make
an edit,
> >> >> >>adding
> >> >> >> >comments to the document might be the best way. You can
also
> >>change
> >> >> >>from
> >> >> >> >"edit" to "suggest" mode if you want your changes to be
> >>provisional
> >> >>and
> >> >> >> >highlighted.
> >> >> >> >
> >> >> >> >a
> >> >> >> >--
> >> >> >> >Andrew Wetmore
> >> >> >> >
> >> >> >>
> >> >> >>>https://na01.safelinks.protection.outlook.com/?url=
> >> >> http%3A%2F%2Fcottage1
> >> >> >>>4
> >> >> >> .
> >> >> >> >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
> >> >> >> 7C1861f488d46a4134ce4f08
> >> >> >> >d55f52a21a%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> >> >> >> 7C636519730868827131
> >> >> >>
> >> >> >>>&sdata=B%2FnPo%2FH6U8AnuJlynjU%2B3eKHfgKu%
> >> >> 2B3fhOkmENjwjIy4%3D&reserved=0
> >> >> >>
> >> >> >>
> >> >> >
> >> >> >
> >> >> >--
> >> >> >Andrew Wetmore
> >> >> >
> >> >>
> >> >>>https://na01.safelinks.protection.outlook.com/?url=
> >> http%3A%2F%2Fcottage1
> >> >>>4
> >> >> .
> >> >> >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
> >> >> 7C9c35244ba8004d7e4ebd08
> >> >> >d55f633d43%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> >> >> 7C636519802209896361
> >> >> >&sdata=ssBcUu2uT%2B9HEL9jV1GEy7yodbGfEliCc7B9Qf
> 1%2BYFA%3D&reserved=0
> >> >>
> >> >>
> >> >
> >> >
> >> >--
> >> >Andrew Wetmore
> >> >
> >>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> http%3A%2F%2Fcottage1
> >>>4
> >> .
> >> >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
> >> 7C01f8158134ae46a8b0d408
> >> >d55f7fc22b%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> >> 7C636519924691296666
> >> >&sdata=wOvxJz3fT%2BW%2FD5mu8LesyUX3P6ptS9QiXdSux1cOy6I%3D&reserved=0
> >>
> >>
> >
> >
> >--
> >Andrew Wetmore
> >
> >https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14
> .
> >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
> 7C4949f27ff1064462e03e08
> >d55f9a8fb3%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C636520039803724615
> >&sdata=QN4WEAtiJmK68PfEKiyCLeFSF95PKyqSSMvKu09xThI%3D&reserved=0
>
>


-- 
Andrew Wetmore

http://cottage14.blogspot.com/

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message