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 14:27:47 GMT
Some of the inherited stuff in subversion may be quite useful, although not
in the first wave of populating the help docs. I see stuff on
internationalization, for instance, that I don't think we are touching yet
in Royale.

Going back to questions about helping people start quickly with Royale, I
think there should be further prominent links on the "getting started" tab
of the website. People would not have to go down the documentation stack to
see these options:

   - Get Apache Royale
   - Build your first Royale app in minutes
   - Migrate from Flex/Flash to Royale
   - See what Royale can do

Each item would link to the appropriate getting-started type material in
the help docs. The fourth link would lead to running versions of the
example apps that we ship, for now, and eventually would lead to examples
of "real" applications built in Royale.

I would even add a "Get started" link on the landing page that moves the
visitor to the Getting Started tab (following the "don't make me think"
principle).



a

On Sat, Jan 20, 2018 at 3:12 AM, Alex Harui <aharui@adobe.com.invalid>
wrote:

> The Flex doc is in a branch in Subversion.  You can browse it here:
> http://svn.apache.org/viewvc/flex/site/branches/flexdoc/
> content/doc/flex/us
> ing/
>
> I think you can use Subversion and clone this:
> https://svn.apache.org/repos/asf/flex/site
> And find it in the branches.
>
> Donations are really painful.  I'd rather not do one again.
>
> -Alex
>
> On 1/19/18, 4:31 PM, "Andrew Wetmore" <cottage14@gmail.com> wrote:
>
> >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%2FD5mu8LesyUX3P6ptS9QiXdSux1cO
> y6I%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%
> >> 7C4949f27ff1064462e03e08
> >> >d55f9a8fb3%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> >> 7C636520039803724615
> >> >&sdata=QN4WEAtiJmK68PfEKiyCLeFSF95PKyqSSMvKu09xThI%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%
> 7C0bae210e5d0e4116c8c808
> >d55f9d3815%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C636520051271808981
> >&sdata=p9nlqU7PE2Bk7nmeAqU0MCf8v%2FHP31A4kC6kJzaKkOg%3D&reserved=0
>
>


-- 
Andrew Wetmore

http://cottage14.blogspot.com/

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