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: Royale in 10 minutes (was Re: Proposed table of contents for Royale help documentation)
Date Fri, 26 Jan 2018 17:09:56 GMT
Hi Andrew,

Responses in-line.

On 1/26/18, 2:48 AM, "Andrew Wetmore" <cottage14@gmail.com> wrote:

>Good morning.
>
>Least thing first: Does the Apache header absolutely need to be in short
>lines with hard line breaks so it takes up so much vertical space in the
>file? Please look at test-apache-header.md and see whether the header laid
>out on fewer lines and trusting to line wrapping works.

I don't know for sure.  There is a header scanning tool that we use and I
just tried it and it didn't mind your reformatting, so that's good enough
for me.
>
>I am fine with your suggestions about where "Hello, World" should be and
>how "Developing an application" might play out. However, this does raise
>the question of whether this sort of help-docs structure is going to have
>an index or other means to locate concepts like "data binding" if it is
>tucked down in a larger set of instructions about applications rather than
>being a entry itself.

IMO, the 10-minute tutorial won't go into any serious detail about data
binding, so "data binding" would have its own section wherever it makes
sense and a link to it from the tutorial.
>
>I think the doc structure is still highly fluid and that we need to either
>hold off on the ToC until we are closer to alpha-release of the
>documentation, or have a less-bulky ToC document. My rough estimate is
>that
>we have stubs for less than 10% of the pages we will eventually have.

IMO, the toc.json is relatively compact and much easier to change.  I'm
not sure how to make it any smaller.  I could probably sit down and crank
out all of the missing stubs in an evening, but is it worth it?  I like
the fact that entries don't show up until we create a page for them.

My 2 cents,
-Alex
>
>On Fri, Jan 26, 2018 at 4:40 AM, Alex Harui <aharui@adobe.com.invalid>
>wrote:
>
>> Hi Andrew,
>>
>> I took a quick peek at the Adobe doc.  I'm not sure "Development Phases"
>> should be the first thing under "Create an application", especially
>>given
>> how the Adobe doc says that some of those sub-topics are not phases.
>> Also, I think there is more than one way to develop an application.
>>
>> My temptation is to leave "Hello, World" as the end of the "Get Started"
>> section.  Getting "Hello World" to work will prove that you have
>>properly
>> installed the SDK.  Then, I would like to suggest tweaking the "Create
>>An
>> Application" section to be where we build an app in 10 minutes.  I think
>> we should start with "Application Structure"  I will discuss the MVC
>> pattern there as an option.  Then the next section would be called
>> something like "A (10 Minute) Tutorial" and the sub-topics will be major
>> steps towards building an example app.  It will take you through
>>building
>> the UI, network access, maybe data-binding, and it will address
>>building,
>> debugging, and deploying the example.  It will pick up enough of the
>> development phase information that I don't think we'll need a separate
>> section for it.
>>
>> I'm shutting down for tonight so I'll see what your thoughts are when I
>> get going again.  I could also draft my version in a branch if you don't
>> want to mess with the develop branch right now.
>>
>> Thoughts?
>> -Alex
>>
>>
>-- 
>Andrew Wetmore
>
>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.
>blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Cfc7c34f4df27449408cf08
>d564aa6bd1%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636525605481253150
>&sdata=gbSwjy2OMLy72u6Jna41ySDuPFO0K5tsjEV7ZZLnEo4%3D&reserved=0

Mime
View raw message