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%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/
