royale-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Wetmore <cottag...@gmail.com>
Subject Re: Royale in 10 minutes (was Re: Proposed table of contents for Royale help documentation)
Date Fri, 26 Jan 2018 19:43:16 GMT
I don't think we need to build out the full ToC up front, rather than PAYG
haha. There are tons of pages that I have not yet listed in the Google doc,
and several decisions we have to make.

For example, we have an Express set of controls and MDL and who knows what
else. I presume we need to explain how these various sets of controls
relate to each other...

On Fri, Jan 26, 2018 at 1:09 PM, Alex Harui <aharui@adobe.com.invalid>
wrote:

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


-- 
Andrew Wetmore

http://cottage14.blogspot.com/

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message