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%2B9HEL9jV1GEy7yodbGfEliCc7B9Qf1%2BYFA%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% > 7C01f8158134ae46a8b0d408 > >d55f7fc22b%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0% > 7C636519924691296666 > >&sdata=wOvxJz3fT%2BW%2FD5mu8LesyUX3P6ptS9QiXdSux1cOy6I%3D&reserved=0 > > -- Andrew Wetmore http://cottage14.blogspot.com/
