FWIW, I believe I have successfully created a develop branch in the royale-docs repo and setup the ApacheRoyaleCI to build the repo with Jekyll so we can use CI for staging builds. I didn't see a way to do staging with GH-Pages.
I will try to put some sort of layout with the TOC navigation in a left pane or something over the next days. One question: On a phone in portrait, what should happen to the TOC? My goal is to get some sort of skeleton up, especially around the "Build your first Royale App in minutes" area and make sure the Express set can deliver on its promise. I'm done for tonight. Should be back online in about 18 hours. -Alex On 1/20/18, 6:27 AM, "Andrew Wetmore" <[email protected]> wrote: >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 <[email protected]> >wrote: > >> The Flex doc is in a branch in Subversion. You can browse it here: >> >>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fsvn.apach >>e.org%2Fviewvc%2Fflex%2Fsite%2Fbranches%2Fflexdoc%2F&data=02%7C01%7Caharu >>i%40adobe.com%7C04b7f65cebed415f0f8b08d560120114%7Cfa7b1b5a7b34438794aed2 >>c178decee1%7C0%7C0%7C636520552807919920&sdata=fDlh86CFmxbpJXy8a4CQPz5Dlmi >>vFgMvYfMGXEsx%2BMs%3D&reserved=0 >> content/doc/flex/us >> ing/ >> >> I think you can use Subversion and clone this: >> >>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fsvn.apac >>he.org%2Frepos%2Fasf%2Fflex%2Fsite&data=02%7C01%7Caharui%40adobe.com%7C04 >>b7f65cebed415f0f8b08d560120114%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0 >>%7C636520552807919920&sdata=%2FTCZADveQlYe6Zgcg%2F5i9lJ%2B%2BceAwvTig5qLf >>m2stXY%3D&reserved=0 >> 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" <[email protected]> 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 <[email protected]> >> >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" <[email protected]> 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 >><[email protected]> >> >> >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" <[email protected]> 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 >> >><[email protected]> >> >> >> >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" <[email protected]> >> 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 >> >> >><[email protected]> >> >> >> >> >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" <[email protected]> >> >> 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%2Fcottage1 >>>4 >> . >> >blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com% >> 7C0bae210e5d0e4116c8c808 >> >d55f9d3815%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0% >> 7C636520051271808981 >> >&sdata=p9nlqU7PE2Bk7nmeAqU0MCf8v%2FHP31A4kC6kJzaKkOg%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%7C04b7f65cebed415f0f8b08 >d560120114%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636520552807919920 >&sdata=aw6%2B5KPXUb55cZD4sF63JX3rjbqTs1KdQ96RekyA4Cg%3D&reserved=0
