royale-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Harui <aha...@adobe.com.INVALID>
Subject Re: Proposed table of contents for Royale help documentation
Date Sat, 20 Jan 2018 00:08:41 GMT
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%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

Mime
View raw message