You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@royale.apache.org by Alex Harui <ah...@adobe.com.INVALID> on 2018/01/27 00:09:08 UTC
Royale Doc Table-of-Contents UX (was Re: Royale Documentation Page
Layout Proposal)
Breaking out a separate thread on this...
Thinking about this some more, I think I can generate an interactive
control with Jekyll, but I don't know how to make it retain state. I
think that might require cookies and/or frames.
For example, let's say the TOC looked like:
Welcome
--High Level View
--Features
----AS3
----MXML
Get Started
--Download
--Hello World
I've already implemented logic in the template to auto-expand the tree to
the document for folks who have direct links. So, if you do a Google
Search and find the link to the MXML page, when you go to that page, the
ToC will automatically look like:
Welcome
--High Level View
--Features
----AS3
---*MXML*
Get Started
If you hit the main doc page, the ToC starts out collapsed so that Get
Started isn't pushed down by a bunch of Welcome sub-topics. So the ToC
initially looks like:
Welcome
Get Started
Now let's say you expand both Welcome and Get Started so you see:
Welcome
--High Level View
--Features
Get Started
--Download
--Hello World
Then you click on Features. The logic that opens trees to direct links is
going to cause the ToC to look like:
Welcome
--High Level View
--Features
Get Started
Even though you had expanded "Get Started" it will collapse when going to
the Features page. That's because, without frames, each page is its own
HTML page. No state about the ToC is retained or shared.
If folks are ok with that, I can probably get that to work.
Thoughts?
-Alex
On 1/26/18, 2:15 PM, "carlos.rovira@gmail.com on behalf of Carlos Rovira"
<carlos.rovira@gmail.com on behalf of carlosrovira@apache.org> wrote:
>Hi Alex,
>
>2018-01-26 21:40 GMT+01:00 Alex Harui <ah...@adobe.com.invalid>:
>
>>One other thing that might need its own thread: I don't know of a Jekyll
>> way to get the ToC to be separately interactive where you can click on
>>the
>> expand/collapse graphics and the ToC will act like a Tree control.
>>There
>> might be a way since I'm new to Jekyll. We could replace the Jekyll
>> generation of the ToC with a Royale app that manages the ToC if we need
>>it
>> to be interactive. Right now everything is static.
>>
>I think this should me more easy since is widely used. We should
>investigate and hope to find and easy way to create a tree navigation.
>As well, I see github pages docs sites that in publication view gives a
>link to the GitHub .md file to edit it.
>So, in the end the docs should be as easy as so we can setup, edit and
>publish in a blink of an eye.
>We should find the right workflow and how to make a tree easily. Then
>creating and editing should be quick for any of us.
>
>A last thing to take into account is about get the right CSS styles for
>code, and other things so .md will be stylized correctly.
>
>I'll continue investigating
>
>Thanks
>
>Carlos
>
>
>
>
>>
>> Thanks,
>> -Alex
>>
>> On 1/26/18, 12:23 PM, "Piotr Zarzycki" <pi...@gmail.com>
>>wrote:
>>
>> >Cool!! :)
>> >
>> >2018-01-26 21:18 GMT+01:00 Carlos Rovira <ca...@apache.org>:
>> >
>> >> Hi,
>> >>
>> >> I'm playing with this concept
>> >>
>> >>
>> >>https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Froyale.c
>> >>odeoscopic.com%2Fdocumentation-page-example%
>> 2F&data=02%7C01%7Caharui%40ad
>> >>obe.com%7Cf3e8feca0c3e404e43e308d564fab63d%
>> 7Cfa7b1b5a7b34438794aed2c178de
>> >>cee1%7C0%7C0%7C636525950328547739&sdata=vuv%
>> 2BuNsHKOO28vssWcdy2TvL1XdxpTS
>> >>floN8ozx1rMk%3D&reserved=0
>> >>
>> >> Here I use:
>> >>
>> >> * The website page header
>> >> * Royale logo white use
>> >> * There's an alternate menu to configure (main website, blog,
>> >>GitHub,...)
>> >> * Search for docs (important)
>> >>
>> >> In content:
>> >>
>> >> * Main page doc title
>> >> * Main doc section content (demo content to show something)
>> >>
>> >> Navigation:
>> >>
>> >> * Menu colapasable (accordion type)
>> >> * Only 2 level
>> >> * Menu content has some of the items I saw here and there, but is
>> >>completly
>> >> demo
>> >>
>> >>
>> >> let me know what do you think
>> >>
>> >> Thanks
>> >>
>> >> --
>> >> Carlos Rovira
>> >>
>> >>https://na01.safelinks.protection.outlook.com/?url=
>> http%3A%2F%2Fabout.me%
>> >>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%
>> 7Cf3e8feca0c3e404e43e308
>> >>d564fab63d%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
>> 7C63652595032854773
>> >>9&sdata=L0tB1P5SOatX1HpGHJ0F928hc2BNwbtg1OCeuXgo8gE%3D&reserved=0
>> >>
>> >
>> >
>> >
>> >--
>> >
>> >Piotr Zarzycki
>> >
>> >Patreon:
>> >*https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fwww.patr
>> >eon.com%2Fpiotrzarzycki&data=02%7C01%7Caharui%40adobe.com%
>> 7Cf3e8feca0c3e40
>> >4e43e308d564fab63d%7Cfa7b1b5a7b34438794aed2c178de
>> cee1%7C0%7C0%7C6365259503
>> >28547739&sdata=X85j16C%2FKJ%2Ff%2FbMOl5O%2BfDDfT%
>> 2Biz9y5mSSBRdhplVKk%3D&re
>> >served=0
>> ><https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fwww.patr
>> >eon.com%2Fpiotrzarzycki&data=02%7C01%7Caharui%40adobe.com%
>> 7Cf3e8feca0c3e40
>> >4e43e308d564fab63d%7Cfa7b1b5a7b34438794aed2c178de
>> cee1%7C0%7C0%7C6365259503
>> >28547739&sdata=X85j16C%2FKJ%2Ff%2FbMOl5O%2BfDDfT%
>> 2Biz9y5mSSBRdhplVKk%3D&re
>> >served=0>*
>>
>>
>
>
>--
>Carlos Rovira
>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2
>Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cd39e795a5bbf4d4b75ef08d5
>650a5e38%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636526017564308812&s
>data=mSD5bnEHF56G6P8J9EiiADnE96xweNkS1aNokcvGrd8%3D&reserved=0
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Gabe Harbs <ha...@gmail.com>.
I’d say “go for it”!
> On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala <bi...@gmail.com> wrote:
>
> Here is a very good example of what the end product would look like:
> https://redux.js.org/
>
> Thanks,
> Om
>
> On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <bi...@gmail.com>
> wrote:
>
>>
>>
>> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com> wrote:
>>
>>> Is this an additional way of viewing the content or a replacement for the
>>> Jenkyll-produced site?
>>>
>>> If it’s the former, I can’t see any reason why not.
>>>
>>
>> It's an additional way. It uses the .md files from the github repo and
>> builds its own site.
>>
>> Thanks,
>> Om
>>
>>
>>>
>>> Harbs
>>>
>>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <bi...@gmail.com>
>>> wrote:
>>>>
>>>> I've been playing around with the tool: GitBook [www.gitbooks.io]
>>>> I was able to connect my personal fork of the royale-docs to my
>>> gitbooks.io
>>>> account. This way, all my .md files are automatically available for
>>> Docs
>>>> creation.
>>>>
>>>> Here is an example I created in a few minutes:
>>>> https://bigosmallm.gitbooks.io/royale-docs-test2/content/v/
>>> develop/Create%20An%20Application.html
>>>>
>>>> The advantages I see using this tool are:
>>>>
>>>> * Seems to be a widely used tool for documentation these days.
>>> NPMjs.org,
>>>> React, Redux, etc. use Gitbook
>>>> * Two way sync between github and gitbook app. That is, you can create
>>> an
>>>> .md file on github and see it on gitbook. You can also create more
>>> content
>>>> using the WYSIWYG editor on Gitbook, which will be synced to the github
>>>> repo.
>>>> * Seems pretty straightforward to create a TOC. It includes support for
>>>> tree structure by default
>>>> * We can choose to use the web app on gitbook.com or use the open
>>>> source(Apache V2 licensed | https://github.com/GitbookIO/gitbook)
>>> command
>>>> line tool. The CLI will help us integrate with our Jenkins build for
>>>> example.
>>>> * Allows users to provide feedback on the site itself
>>>> * Allows us to point the docs site to our custom domain address
>>>>
>>>>
>>>> If there is more interest in trying this out, I can set up an
>>> Organization
>>>> account (free) and add users as needed.
>>>>
>>>> Thanks,
>>>> Om
>>>>
>>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <co...@gmail.com>
>>> wrote:
>>>>
>>>>> If the ToC accordions properly and we need three levels, I do not see
>>> why
>>>>> three levels would cause more confusion than two levels. If this is a
>>>>> resource providing information people are going to need to use Royale,
>>> and
>>>>> if that information is not readily available elsewhere, then we should
>>> make
>>>>> the ToC fit the information, not the other way around.
>>>>>
>>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
>>> carlosrovira@apache.org>
>>>>> wrote:
>>>>>
>>>>>> Hi Alex,
>>>>>>
>>>>>> for TOC. One think that's very important to me: Please only *two
>>> levels*
>>>>> in
>>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's the
>>>>>> standard right now and a three level only created confusion. Again see
>>>>>> Angular and React sites to match what they did and take it as a
>>>>> reference.
>>>>>>
>>>>>> For states. I think the trick here is that a .md page has some
>>> variables
>>>>>> that will make the right top level branch open in TOC and as well make
>>>>> the
>>>>>> right sub option appears as selected (strong type) and without link.
>>> As
>>>>> we
>>>>>> are dealing with static GitHub pages I think there's no concept of
>>>>>> component, only that all pages has the TOC added to the sidebar.
>>>>>>
>>>>>>
>>>>>>
>>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>>>>>>
>>>>>>> What you describe sounds fine to me. I don't think we need to worry
>>>>> about
>>>>>>> breadcrumbs and state and helping people go backwards through their
>>>>>> series
>>>>>>> of clicks.
>>>>>>>
>>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <aharui@adobe.com.invalid
>>>>
>>>>>>> wrote:
>>>>>>>
>>>>>>>> Breaking out a separate thread on this...
>>>>>>>>
>>>>>>>> Thinking about this some more, I think I can generate an interactive
>>>>>>>> control with Jekyll, but I don't know how to make it retain state.
>>> I
>>>>>>>> think that might require cookies and/or frames.
>>>>>>>>
>>>>>>>> For example, let's say the TOC looked like:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> ----AS3
>>>>>>>> ----MXML
>>>>>>>> Get Started
>>>>>>>> --Download
>>>>>>>> --Hello World
>>>>>>>>
>>>>>>>> I've already implemented logic in the template to auto-expand the
>>>>> tree
>>>>>> to
>>>>>>>> the document for folks who have direct links. So, if you do a
>>> Google
>>>>>>>> Search and find the link to the MXML page, when you go to that page,
>>>>>> the
>>>>>>>> ToC will automatically look like:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> ----AS3
>>>>>>>> ---*MXML*
>>>>>>>> Get Started
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> If you hit the main doc page, the ToC starts out collapsed so that
>>>>> Get
>>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So the
>>>>> ToC
>>>>>>>> initially looks like:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> Get Started
>>>>>>>>
>>>>>>>> Now let's say you expand both Welcome and Get Started so you see:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> Get Started
>>>>>>>> --Download
>>>>>>>> --Hello World
>>>>>>>>
>>>>>>>> Then you click on Features. The logic that opens trees to direct
>>>>> links
>>>>>>> is
>>>>>>>> going to cause the ToC to look like:
>>>>>>>>
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> Get Started
>>>>>>>>
>>>>>>>> Even though you had expanded "Get Started" it will collapse when
>>>>> going
>>>>>> to
>>>>>>>> the Features page. That's because, without frames, each page is its
>>>>>> own
>>>>>>>> HTML page. No state about the ToC is retained or shared.
>>>>>>>>
>>>>>>>> If folks are ok with that, I can probably get that to work.
>>>>>>>>
>>>>>>>> Thoughts?
>>>>>>>> -Alex
>>>>>>>>
>>>>>>> --
>>>>>>> Andrew Wetmore
>>>>>>>
>>>>>>> http://cottage14.blogspot.com/
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>>>>>> Virus-free.
>>>>>>> www.avast.com
>>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Carlos Rovira
>>>>>> http://about.me/carlosrovira
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Andrew Wetmore
>>>>>
>>>>> http://cottage14.blogspot.com/
>>>>>
>>>
>>>
>>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Alex Harui <ah...@adobe.com.INVALID>.
OK, so to be clear, you are proposing replacing Jekyll with Gitbook.
It looked to me that Gitbook doesn't have as smooth a publishing
mechanism. I'll go with whatever the majority wants to do, but I really
just want to focus on content instead of debating the merits of
alternatives to Gitbook. We are already many hours in on Jekyll. I think
it works well enough. And we can control every pixel on the screen.
My 2 cents,
-Alex
On 1/29/18, 12:23 AM, "omuppi1@gmail.com on behalf of OmPrakash Muppirala"
<omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>On Sun, Jan 28, 2018 at 11:56 PM, Alex Harui <ah...@adobe.com.invalid>
>wrote:
>
>> I'm still confused. I think we agreed to use GH Pages. AFAICT, GH
>>Pages
>> uses Jekyll and Markdown.
>
>
>Jekyll is a general purpose static website generator. Gitbook is built
>specifically for documentation.
>
>
>> Jekyll expects a certain layout like templates
>> in a _layout folder. I have put a template in there. I don't
>>understand
>> using a different production system that doesn't use Jekyll and its way
>>of
>> laying out text.
>>
>
>
>You can publish to GH pages without using Jekyll:
>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhelp.gith
>ub.com%2Farticles%2Fusing-a-static-site-generator-other-than-jekyll%2F&dat
>a=02%7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1b
>5a7b34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=GsI6eXK7%2F2
>zKtKHD2dsCQVQ5QbKwdyk4BeP4PWdGbKY%3D&reserved=0
>
>Here's how we can do it with Gitbook:
>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fsangsoonam
>.github.io%2F2016%2F08%2F02%2Fpublish-gitbook-to-your-github-pages.html&da
>ta=02%7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1
>b5a7b34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=iVvLnTi96t%
>2BB9RzzJMbcga3Vk1vQymNPOSAC0y%2BzKoo%3D&reserved=0
>
>Thanks,
>Om
>
>
>>
>> -Alex
>>
>> On 1/28/18, 11:11 PM, "omuppi1@gmail.com on behalf of OmPrakash
>>Muppirala"
>> <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>>
>> >This does not use the Jekyll workflow. This uses the .md files
>>directly.
>> >
>> >Thanks,
>> >Om
>> >
>> >On Jan 28, 2018 10:57 PM, "Alex Harui" <ah...@adobe.com.invalid>
>>wrote:
>> >
>> >I don’t get it. There is a Jekyll template in our repo. The link I
>>just
>> >clicked on did not appear to use it.
>> >
>> >-Alex
>> >
>> >On 1/28/18, 4:41 AM, "Andrew Wetmore" <co...@gmail.com> wrote:
>> >
>> >>Yeah...the one thing it does not have is an expanding-collapsing ToC.
>>The
>> >>scrolling is not bad, but the intimidation effect of endless topic
>>titles
>> >>can be large. For me that is a usability negative...but not a
>> >>deal-killer.
>> >>
>> >>On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <ha...@gmail.com>
>> >>wrote:
>> >>
>> >>> BTW:
>> >>>
>> >>> That site has 3 levels in the table of contents:
>> >>>
>> >>>https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fredux.j
>> >>>s
>> >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&
>> data=02%7C0
>> >>>1
>> >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
>> 8547%7Cfa7b1b5a7b344
>> >>>3
>> >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=
>> 4Bdy4FThikLGQukS0S
>> >>>S
>> >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0 <
>> >>>
>> >>>https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fredux.j
>> >>>s
>> >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&
>> data=02%7C0
>> >>>1
>> >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
>> 8547%7Cfa7b1b5a7b344
>> >>>3
>> >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=
>> 4Bdy4FThikLGQukS0S
>> >>>S
>> >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0>
>> >>>
>> >>> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala
>> >>><bi...@gmail.com>
>> >>> wrote:
>> >>> >
>> >>> > Here is a very good example of what the end product would look
>>like:
>> >>> >
>> >>>https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fredux.j
>> >>>s
>> >>>.org%2F&data=02%7C01%7Caharui%40adobe.com%
>> 7Ce35c7c4743804324141308d5664c
>> >>>8
>> >>>547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
>> 7C636527401200834465&sdat
>> >>>a
>> >>>=GrTlTr5PCqHK6qS9pg9dKcKyRtO6BJU1xpxLGzWYOsY%3D&reserved=0
>> >>> >
>> >>> > Thanks,
>> >>> > Om
>> >>> >
>> >>> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <
>> >>> bigosmallm@gmail.com>
>> >>> > wrote:
>> >>> >
>> >>> >>
>> >>> >>
>> >>> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs
>><ha...@gmail.com>
>> >>> wrote:
>> >>> >>
>> >>> >>> Is this an additional way of viewing the content or a
>>replacement
>> >>>for
>> >>> the
>> >>> >>> Jenkyll-produced site?
>> >>> >>>
>> >>> >>> If it’s the former, I can’t see any reason why not.
>> >>> >>>
>> >>> >>
>> >>> >> It's an additional way. It uses the .md files from the github
>>repo
>> >>>and
>> >>> >> builds its own site.
>> >>> >>
>> >>> >> Thanks,
>> >>> >> Om
>> >>> >>
>> >>> >>
>> >>> >>>
>> >>> >>> Harbs
>> >>> >>>
>> >>> >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <
>> >>> bigosmallm@gmail.com>
>> >>> >>> wrote:
>> >>> >>>>
>> >>> >>>> I've been playing around with the tool: GitBook
>> >>>[https://na01.safelinks.protection.outlook.com/?url=
>>
>>https://na01.safelinks.protection.outlook.com/?url=www.gitbooks.io&data=0
>>2%7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1b5a
>>7b34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=FnygcKm4rNdnS
>>KgB5Ig22g8RK8%2FJ4TBu6fFkFiyGXac%3D&reserved=0&data
>> >>>=
>> >>>02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
>> 8547%7Cfa7b1b
>> >>>5
>> >>>a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&
>> sdata=VI3BEHW9v7G
>> >>>P
>> >>>nAlTOg2gEp%2FgLrF61UFUShsrxY1wG7I%3D&reserved=0]
>> >>> >>>> I was able to connect my personal fork of the royale-docs to my
>> >>> >>> gitbooks.io
>> >>> >>>> account. This way, all my .md files are automatically
>>available
>> >>>for
>> >>> >>> Docs
>> >>> >>>> creation.
>> >>> >>>>
>> >>> >>>> Here is an example I created in a few minutes:
>> >>> >>>>
>> >>>https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fbigosma
>> >>>l
>> >>>lm.gitbooks.io%2Froyale-docs-test2%2Fcontent%2Fv%2F&
>> data=02%7C01%7Caharu
>> >>>i
>> >>>%40adobe.com%7Ce35c7c4743804324141308d5664c
>> 8547%7Cfa7b1b5a7b34438794aed2
>> >>>c
>> >>>178decee1%7C0%7C0%7C636527401200834465&sdata=
>> wYN9q4TD9UFz8rwXmzoh8QDc16E
>> >>>n
>> >>>Q64NDLMa4XKvMdg%3D&reserved=0
>> >>> >>> develop/Create%20An%20Application.html
>> >>> >>>>
>> >>> >>>> The advantages I see using this tool are:
>> >>> >>>>
>> >>> >>>> * Seems to be a widely used tool for documentation these days.
>> >>> >>> NPMjs.org,
>> >>> >>>> React, Redux, etc. use Gitbook
>> >>> >>>> * Two way sync between github and gitbook app. That is, you
>>can
>> >>> create
>> >>> >>> an
>> >>> >>>> .md file on github and see it on gitbook. You can also create
>> >>>more
>> >>> >>> content
>> >>> >>>> using the WYSIWYG editor on Gitbook, which will be synced to
>>the
>> >>> github
>> >>> >>>> repo.
>> >>> >>>> * Seems pretty straightforward to create a TOC. It includes
>> >>>support
>> >>> for
>> >>> >>>> tree structure by default
>> >>> >>>> * We can choose to use the web app on gitbook.com or use the
>>open
>> >>> >>>> source(Apache V2 licensed |
>>
>>>>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithu
>>>>>b
>> .
>> >>>c
>> >>>om%2FGitbookIO%2Fgitbook&data=02%7C01%7Caharui%40adobe.com
>> %7Ce35c7c47438
>> >>>0
>> >>>4324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
>> cee1%7C0%7C0%7C636527
>> >>>4
>> >>>01200834465&sdata=9yrCy9F6C7auYCI%2FEjfdLi8gTkkma%2FN4rURUrFDU%
>> 2FZI%3D&r
>> >>>e
>> >>>served=0)
>> >>> >>> command
>> >>> >>>> line tool. The CLI will help us integrate with our Jenkins
>>build
>> >>>for
>> >>> >>>> example.
>> >>> >>>> * Allows users to provide feedback on the site itself
>> >>> >>>> * Allows us to point the docs site to our custom domain address
>> >>> >>>>
>> >>> >>>>
>> >>> >>>> If there is more interest in trying this out, I can set up an
>> >>> >>> Organization
>> >>> >>>> account (free) and add users as needed.
>> >>> >>>>
>> >>> >>>> Thanks,
>> >>> >>>> Om
>> >>> >>>>
>> >>> >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore
>> >>><co...@gmail.com>
>> >>> >>> wrote:
>> >>> >>>>
>> >>> >>>>> If the ToC accordions properly and we need three levels, I do
>>not
>> >>>see
>> >>> >>> why
>> >>> >>>>> three levels would cause more confusion than two levels. If
>>this
>> >>>is a
>> >>> >>>>> resource providing information people are going to need to use
>> >>> Royale,
>> >>> >>> and
>> >>> >>>>> if that information is not readily available elsewhere, then
>>we
>> >>> should
>> >>> >>> make
>> >>> >>>>> the ToC fit the information, not the other way around.
>> >>> >>>>>
>> >>> >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
>> >>> >>> carlosrovira@apache.org>
>> >>> >>>>> wrote:
>> >>> >>>>>
>> >>> >>>>>> Hi Alex,
>> >>> >>>>>>
>> >>> >>>>>> for TOC. One think that's very important to me: Please only
>>*two
>> >>> >>> levels*
>> >>> >>>>> in
>> >>> >>>>>> TOC. For simplicity and clarity. Like the demo page I did.
>>It's
>> >>>the
>> >>> >>>>>> standard right now and a three level only created confusion.
>> >>>Again
>> >>> see
>> >>> >>>>>> Angular and React sites to match what they did and take it
>>as a
>> >>> >>>>> reference.
>> >>> >>>>>>
>> >>> >>>>>> For states. I think the trick here is that a .md page has
>>some
>> >>> >>> variables
>> >>> >>>>>> that will make the right top level branch open in TOC and as
>> >>>well
>> >>> make
>> >>> >>>>> the
>> >>> >>>>>> right sub option appears as selected (strong type) and
>>without
>> >>>link.
>> >>> >>> As
>> >>> >>>>> we
>> >>> >>>>>> are dealing with static GitHub pages I think there's no
>>concept
>> >>>of
>> >>> >>>>>> component, only that all pages has the TOC added to the
>>sidebar.
>> >>> >>>>>>
>> >>> >>>>>>
>> >>> >>>>>>
>> >>> >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore
>><co...@gmail.com>:
>> >>> >>>>>>
>> >>> >>>>>>> What you describe sounds fine to me. I don't think we need
>>to
>> >>>worry
>> >>> >>>>> about
>> >>> >>>>>>> breadcrumbs and state and helping people go backwards
>>through
>> >>>their
>> >>> >>>>>> series
>> >>> >>>>>>> of clicks.
>> >>> >>>>>>>
>> >>> >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui
>> >>> <aharui@adobe.com.invalid
>> >>> >>>>
>> >>> >>>>>>> wrote:
>> >>> >>>>>>>
>> >>> >>>>>>>> Breaking out a separate thread on this...
>> >>> >>>>>>>>
>> >>> >>>>>>>> Thinking about this some more, I think I can generate an
>> >>> interactive
>> >>> >>>>>>>> control with Jekyll, but I don't know how to make it retain
>> >>>state.
>> >>> >>> I
>> >>> >>>>>>>> think that might require cookies and/or frames.
>> >>> >>>>>>>>
>> >>> >>>>>>>> For example, let's say the TOC looked like:
>> >>> >>>>>>>>
>> >>> >>>>>>>> Welcome
>> >>> >>>>>>>> --High Level View
>> >>> >>>>>>>> --Features
>> >>> >>>>>>>> ----AS3
>> >>> >>>>>>>> ----MXML
>> >>> >>>>>>>> Get Started
>> >>> >>>>>>>> --Download
>> >>> >>>>>>>> --Hello World
>> >>> >>>>>>>>
>> >>> >>>>>>>> I've already implemented logic in the template to
>>auto-expand
>> >>>the
>> >>> >>>>> tree
>> >>> >>>>>> to
>> >>> >>>>>>>> the document for folks who have direct links. So, if you
>>do a
>> >>> >>> Google
>> >>> >>>>>>>> Search and find the link to the MXML page, when you go to
>>that
>> >>> page,
>> >>> >>>>>> the
>> >>> >>>>>>>> ToC will automatically look like:
>> >>> >>>>>>>>
>> >>> >>>>>>>> Welcome
>> >>> >>>>>>>> --High Level View
>> >>> >>>>>>>> --Features
>> >>> >>>>>>>> ----AS3
>> >>> >>>>>>>> ---*MXML*
>> >>> >>>>>>>> Get Started
>> >>> >>>>>>>>
>> >>> >>>>>>>>
>> >>> >>>>>>>>
>> >>> >>>>>>>> If you hit the main doc page, the ToC starts out collapsed
>>so
>> >>>that
>> >>> >>>>> Get
>> >>> >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics.
>> >>>So
>> >>> the
>> >>> >>>>> ToC
>> >>> >>>>>>>> initially looks like:
>> >>> >>>>>>>>
>> >>> >>>>>>>> Welcome
>> >>> >>>>>>>> Get Started
>> >>> >>>>>>>>
>> >>> >>>>>>>> Now let's say you expand both Welcome and Get Started so
>>you
>> >>>see:
>> >>> >>>>>>>>
>> >>> >>>>>>>> Welcome
>> >>> >>>>>>>> --High Level View
>> >>> >>>>>>>> --Features
>> >>> >>>>>>>> Get Started
>> >>> >>>>>>>> --Download
>> >>> >>>>>>>> --Hello World
>> >>> >>>>>>>>
>> >>> >>>>>>>> Then you click on Features. The logic that opens trees to
>> >>>direct
>> >>> >>>>> links
>> >>> >>>>>>> is
>> >>> >>>>>>>> going to cause the ToC to look like:
>> >>> >>>>>>>>
>> >>> >>>>>>>>
>> >>> >>>>>>>> Welcome
>> >>> >>>>>>>> --High Level View
>> >>> >>>>>>>> --Features
>> >>> >>>>>>>> Get Started
>> >>> >>>>>>>>
>> >>> >>>>>>>> Even though you had expanded "Get Started" it will collapse
>> >>>when
>> >>> >>>>> going
>> >>> >>>>>> to
>> >>> >>>>>>>> the Features page. That's because, without frames, each
>>page
>> >>>is
>> >>> its
>> >>> >>>>>> own
>> >>> >>>>>>>> HTML page. No state about the ToC is retained or shared.
>> >>> >>>>>>>>
>> >>> >>>>>>>> If folks are ok with that, I can probably get that to work.
>> >>> >>>>>>>>
>> >>> >>>>>>>> Thoughts?
>> >>> >>>>>>>> -Alex
>> >>> >>>>>>>>
>> >>> >>>>>>> --
>> >>> >>>>>>> Andrew Wetmore
>> >>> >>>>>>>
>> >>> >>>>>>>
>> >>>https://na01.safelinks.protection.outlook.com/?url=
>> http%3A%2F%2Fcottage1
>> >>>4
>> >>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
>> 7Ce35c7c4743804324141
>> >>>3
>> >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
>> cee1%7C0%7C0%7C63652740120083
>> >>>4
>> >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
>> >>> >>>>>>>
>> >>> >>>>>>>
>> >>> >>>>>>>
>> >>> >>>>>>>
>> >>> >>>>>>>
>> >>> >>>>>>>
>> >>><https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fwww.av
>> >>>a
>> >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%
>> 7C01%7Caharui%40a
>> >>>d
>> >>>obe.com%7Ce35c7c4743804324141308d5664c8547%
>> 7Cfa7b1b5a7b34438794aed2c178d
>> >>>e
>>
>>>>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j
>> mB
>> >>>P
>> >>>S86IdsRNiQ%3D&reserved=0
>> >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>> >>>>>>> Virus-free.
>> >>> >>>>>>>
>> >>>https://na01.safelinks.protection.outlook.com/?url=
>>
>>https://na01.safelinks.protection.outlook.com/?url=www.avast.com&data=02%
>>7C01%7Caharui%40adobe.com%7C0ebe0d56d8294e04a6ee08d566f1aaa1%7Cfa7b1b5a7b
>>34438794aed2c178decee1%7C0%7C0%7C636528110492215042&sdata=nJd8J9PJajaOVPd
>>3yRA%2FOe4P1p6BaUUedsJ1MwulX30%3D&reserved=0&data=02
>> >>>%
>> >>>7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
>> 8547%7Cfa7b1b5a7
>> >>>b
>> >>>34438794aed2c178decee1%7C0%7C0%7C636527401200834465&
>> sdata=zkLsd1ijA9LimW
>> >>>6
>> >>>%2F3Kfze8CwM%2Fn2ty8Twehti%2B8QbXA%3D&reserved=0
>> >>> >>>>>>>
>> >>><https://na01.safelinks.protection.outlook.com/?url=
>> https%3A%2F%2Fwww.av
>> >>>a
>> >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%
>> 7C01%7Caharui%40a
>> >>>d
>> >>>obe.com%7Ce35c7c4743804324141308d5664c8547%
>> 7Cfa7b1b5a7b34438794aed2c178d
>> >>>e
>>
>>>>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j
>> mB
>> >>>P
>> >>>S86IdsRNiQ%3D&reserved=0
>> >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>> >>> >>>>>>>
>> >>> >>>>>>
>> >>> >>>>>>
>> >>> >>>>>>
>> >>> >>>>>> --
>> >>> >>>>>> Carlos Rovira
>> >>> >>>>>>
>> >>>https://na01.safelinks.protection.outlook.com/?url=
>> http%3A%2F%2Fabout.me
>> >>>%
>> >>>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%
>> 7Ce35c7c474380432414130
>> >>>8
>> >>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
>> 7C6365274012008344
>> >>>6
>> >>>5&sdata=3LH%2BI93bLwNWxoOGx6eo6A2MBQaxxUMrNrufjXIh6Bo%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%
>> 7Ce35c7c4743804324141
>> >>>3
>> >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
>> cee1%7C0%7C0%7C63652740120083
>> >>>4
>> >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%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%
>> 7Ce35c7c474380432414130
>> >>8
>> >>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
>> 7C63652740120083446
>> >>5
>> >>&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
>>
>>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Sun, Jan 28, 2018 at 11:56 PM, Alex Harui <ah...@adobe.com.invalid>
wrote:
> I'm still confused. I think we agreed to use GH Pages. AFAICT, GH Pages
> uses Jekyll and Markdown.
Jekyll is a general purpose static website generator. Gitbook is built
specifically for documentation.
> Jekyll expects a certain layout like templates
> in a _layout folder. I have put a template in there. I don't understand
> using a different production system that doesn't use Jekyll and its way of
> laying out text.
>
You can publish to GH pages without using Jekyll:
https://help.github.com/articles/using-a-static-site-generator-other-than-jekyll/
Here's how we can do it with Gitbook:
http://sangsoonam.github.io/2016/08/02/publish-gitbook-to-your-github-pages.html
Thanks,
Om
>
> -Alex
>
> On 1/28/18, 11:11 PM, "omuppi1@gmail.com on behalf of OmPrakash Muppirala"
> <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
> >This does not use the Jekyll workflow. This uses the .md files directly.
> >
> >Thanks,
> >Om
> >
> >On Jan 28, 2018 10:57 PM, "Alex Harui" <ah...@adobe.com.invalid> wrote:
> >
> >I don’t get it. There is a Jekyll template in our repo. The link I just
> >clicked on did not appear to use it.
> >
> >-Alex
> >
> >On 1/28/18, 4:41 AM, "Andrew Wetmore" <co...@gmail.com> wrote:
> >
> >>Yeah...the one thing it does not have is an expanding-collapsing ToC. The
> >>scrolling is not bad, but the intimidation effect of endless topic titles
> >>can be large. For me that is a usability negative...but not a
> >>deal-killer.
> >>
> >>On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <ha...@gmail.com>
> >>wrote:
> >>
> >>> BTW:
> >>>
> >>> That site has 3 levels in the table of contents:
> >>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fredux.j
> >>>s
> >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&
> data=02%7C0
> >>>1
> >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7b344
> >>>3
> >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=
> 4Bdy4FThikLGQukS0S
> >>>S
> >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0 <
> >>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fredux.j
> >>>s
> >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&
> data=02%7C0
> >>>1
> >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7b344
> >>>3
> >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=
> 4Bdy4FThikLGQukS0S
> >>>S
> >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0>
> >>>
> >>> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala
> >>><bi...@gmail.com>
> >>> wrote:
> >>> >
> >>> > Here is a very good example of what the end product would look like:
> >>> >
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fredux.j
> >>>s
> >>>.org%2F&data=02%7C01%7Caharui%40adobe.com%
> 7Ce35c7c4743804324141308d5664c
> >>>8
> >>>547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C636527401200834465&sdat
> >>>a
> >>>=GrTlTr5PCqHK6qS9pg9dKcKyRtO6BJU1xpxLGzWYOsY%3D&reserved=0
> >>> >
> >>> > Thanks,
> >>> > Om
> >>> >
> >>> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <
> >>> bigosmallm@gmail.com>
> >>> > wrote:
> >>> >
> >>> >>
> >>> >>
> >>> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com>
> >>> wrote:
> >>> >>
> >>> >>> Is this an additional way of viewing the content or a replacement
> >>>for
> >>> the
> >>> >>> Jenkyll-produced site?
> >>> >>>
> >>> >>> If it’s the former, I can’t see any reason why not.
> >>> >>>
> >>> >>
> >>> >> It's an additional way. It uses the .md files from the github repo
> >>>and
> >>> >> builds its own site.
> >>> >>
> >>> >> Thanks,
> >>> >> Om
> >>> >>
> >>> >>
> >>> >>>
> >>> >>> Harbs
> >>> >>>
> >>> >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <
> >>> bigosmallm@gmail.com>
> >>> >>> wrote:
> >>> >>>>
> >>> >>>> I've been playing around with the tool: GitBook
> >>>[https://na01.safelinks.protection.outlook.com/?url=
> www.gitbooks.io&data
> >>>=
> >>>02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b
> >>>5
> >>>a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&
> sdata=VI3BEHW9v7G
> >>>P
> >>>nAlTOg2gEp%2FgLrF61UFUShsrxY1wG7I%3D&reserved=0]
> >>> >>>> I was able to connect my personal fork of the royale-docs to my
> >>> >>> gitbooks.io
> >>> >>>> account. This way, all my .md files are automatically available
> >>>for
> >>> >>> Docs
> >>> >>>> creation.
> >>> >>>>
> >>> >>>> Here is an example I created in a few minutes:
> >>> >>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fbigosma
> >>>l
> >>>lm.gitbooks.io%2Froyale-docs-test2%2Fcontent%2Fv%2F&
> data=02%7C01%7Caharu
> >>>i
> >>>%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7b34438794aed2
> >>>c
> >>>178decee1%7C0%7C0%7C636527401200834465&sdata=
> wYN9q4TD9UFz8rwXmzoh8QDc16E
> >>>n
> >>>Q64NDLMa4XKvMdg%3D&reserved=0
> >>> >>> develop/Create%20An%20Application.html
> >>> >>>>
> >>> >>>> The advantages I see using this tool are:
> >>> >>>>
> >>> >>>> * Seems to be a widely used tool for documentation these days.
> >>> >>> NPMjs.org,
> >>> >>>> React, Redux, etc. use Gitbook
> >>> >>>> * Two way sync between github and gitbook app. That is, you can
> >>> create
> >>> >>> an
> >>> >>>> .md file on github and see it on gitbook. You can also create
> >>>more
> >>> >>> content
> >>> >>>> using the WYSIWYG editor on Gitbook, which will be synced to the
> >>> github
> >>> >>>> repo.
> >>> >>>> * Seems pretty straightforward to create a TOC. It includes
> >>>support
> >>> for
> >>> >>>> tree structure by default
> >>> >>>> * We can choose to use the web app on gitbook.com or use the open
> >>> >>>> source(Apache V2 licensed |
> >>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub
> .
> >>>c
> >>>om%2FGitbookIO%2Fgitbook&data=02%7C01%7Caharui%40adobe.com
> %7Ce35c7c47438
> >>>0
> >>>4324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
> cee1%7C0%7C0%7C636527
> >>>4
> >>>01200834465&sdata=9yrCy9F6C7auYCI%2FEjfdLi8gTkkma%2FN4rURUrFDU%
> 2FZI%3D&r
> >>>e
> >>>served=0)
> >>> >>> command
> >>> >>>> line tool. The CLI will help us integrate with our Jenkins build
> >>>for
> >>> >>>> example.
> >>> >>>> * Allows users to provide feedback on the site itself
> >>> >>>> * Allows us to point the docs site to our custom domain address
> >>> >>>>
> >>> >>>>
> >>> >>>> If there is more interest in trying this out, I can set up an
> >>> >>> Organization
> >>> >>>> account (free) and add users as needed.
> >>> >>>>
> >>> >>>> Thanks,
> >>> >>>> Om
> >>> >>>>
> >>> >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore
> >>><co...@gmail.com>
> >>> >>> wrote:
> >>> >>>>
> >>> >>>>> If the ToC accordions properly and we need three levels, I do not
> >>>see
> >>> >>> why
> >>> >>>>> three levels would cause more confusion than two levels. If this
> >>>is a
> >>> >>>>> resource providing information people are going to need to use
> >>> Royale,
> >>> >>> and
> >>> >>>>> if that information is not readily available elsewhere, then we
> >>> should
> >>> >>> make
> >>> >>>>> the ToC fit the information, not the other way around.
> >>> >>>>>
> >>> >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
> >>> >>> carlosrovira@apache.org>
> >>> >>>>> wrote:
> >>> >>>>>
> >>> >>>>>> Hi Alex,
> >>> >>>>>>
> >>> >>>>>> for TOC. One think that's very important to me: Please only *two
> >>> >>> levels*
> >>> >>>>> in
> >>> >>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's
> >>>the
> >>> >>>>>> standard right now and a three level only created confusion.
> >>>Again
> >>> see
> >>> >>>>>> Angular and React sites to match what they did and take it as a
> >>> >>>>> reference.
> >>> >>>>>>
> >>> >>>>>> For states. I think the trick here is that a .md page has some
> >>> >>> variables
> >>> >>>>>> that will make the right top level branch open in TOC and as
> >>>well
> >>> make
> >>> >>>>> the
> >>> >>>>>> right sub option appears as selected (strong type) and without
> >>>link.
> >>> >>> As
> >>> >>>>> we
> >>> >>>>>> are dealing with static GitHub pages I think there's no concept
> >>>of
> >>> >>>>>> component, only that all pages has the TOC added to the sidebar.
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
> >>> >>>>>>
> >>> >>>>>>> What you describe sounds fine to me. I don't think we need to
> >>>worry
> >>> >>>>> about
> >>> >>>>>>> breadcrumbs and state and helping people go backwards through
> >>>their
> >>> >>>>>> series
> >>> >>>>>>> of clicks.
> >>> >>>>>>>
> >>> >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui
> >>> <aharui@adobe.com.invalid
> >>> >>>>
> >>> >>>>>>> wrote:
> >>> >>>>>>>
> >>> >>>>>>>> Breaking out a separate thread on this...
> >>> >>>>>>>>
> >>> >>>>>>>> Thinking about this some more, I think I can generate an
> >>> interactive
> >>> >>>>>>>> control with Jekyll, but I don't know how to make it retain
> >>>state.
> >>> >>> I
> >>> >>>>>>>> think that might require cookies and/or frames.
> >>> >>>>>>>>
> >>> >>>>>>>> For example, let's say the TOC looked like:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> ----AS3
> >>> >>>>>>>> ----MXML
> >>> >>>>>>>> Get Started
> >>> >>>>>>>> --Download
> >>> >>>>>>>> --Hello World
> >>> >>>>>>>>
> >>> >>>>>>>> I've already implemented logic in the template to auto-expand
> >>>the
> >>> >>>>> tree
> >>> >>>>>> to
> >>> >>>>>>>> the document for folks who have direct links. So, if you do a
> >>> >>> Google
> >>> >>>>>>>> Search and find the link to the MXML page, when you go to that
> >>> page,
> >>> >>>>>> the
> >>> >>>>>>>> ToC will automatically look like:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> ----AS3
> >>> >>>>>>>> ---*MXML*
> >>> >>>>>>>> Get Started
> >>> >>>>>>>>
> >>> >>>>>>>>
> >>> >>>>>>>>
> >>> >>>>>>>> If you hit the main doc page, the ToC starts out collapsed so
> >>>that
> >>> >>>>> Get
> >>> >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics.
> >>>So
> >>> the
> >>> >>>>> ToC
> >>> >>>>>>>> initially looks like:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> Get Started
> >>> >>>>>>>>
> >>> >>>>>>>> Now let's say you expand both Welcome and Get Started so you
> >>>see:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> Get Started
> >>> >>>>>>>> --Download
> >>> >>>>>>>> --Hello World
> >>> >>>>>>>>
> >>> >>>>>>>> Then you click on Features. The logic that opens trees to
> >>>direct
> >>> >>>>> links
> >>> >>>>>>> is
> >>> >>>>>>>> going to cause the ToC to look like:
> >>> >>>>>>>>
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> Get Started
> >>> >>>>>>>>
> >>> >>>>>>>> Even though you had expanded "Get Started" it will collapse
> >>>when
> >>> >>>>> going
> >>> >>>>>> to
> >>> >>>>>>>> the Features page. That's because, without frames, each page
> >>>is
> >>> its
> >>> >>>>>> own
> >>> >>>>>>>> HTML page. No state about the ToC is retained or shared.
> >>> >>>>>>>>
> >>> >>>>>>>> If folks are ok with that, I can probably get that to work.
> >>> >>>>>>>>
> >>> >>>>>>>> Thoughts?
> >>> >>>>>>>> -Alex
> >>> >>>>>>>>
> >>> >>>>>>> --
> >>> >>>>>>> Andrew Wetmore
> >>> >>>>>>>
> >>> >>>>>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> http%3A%2F%2Fcottage1
> >>>4
> >>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
> 7Ce35c7c4743804324141
> >>>3
> >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
> cee1%7C0%7C0%7C63652740120083
> >>>4
> >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>><https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fwww.av
> >>>a
> >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%
> 7C01%7Caharui%40a
> >>>d
> >>>obe.com%7Ce35c7c4743804324141308d5664c8547%
> 7Cfa7b1b5a7b34438794aed2c178d
> >>>e
> >>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j
> mB
> >>>P
> >>>S86IdsRNiQ%3D&reserved=0
> >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>> >>>>>>> Virus-free.
> >>> >>>>>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> www.avast.com&data=02
> >>>%
> >>>7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7
> >>>b
> >>>34438794aed2c178decee1%7C0%7C0%7C636527401200834465&
> sdata=zkLsd1ijA9LimW
> >>>6
> >>>%2F3Kfze8CwM%2Fn2ty8Twehti%2B8QbXA%3D&reserved=0
> >>> >>>>>>>
> >>><https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fwww.av
> >>>a
> >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%
> 7C01%7Caharui%40a
> >>>d
> >>>obe.com%7Ce35c7c4743804324141308d5664c8547%
> 7Cfa7b1b5a7b34438794aed2c178d
> >>>e
> >>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j
> mB
> >>>P
> >>>S86IdsRNiQ%3D&reserved=0
> >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
> >>> >>>>>>>
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>> --
> >>> >>>>>> Carlos Rovira
> >>> >>>>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> http%3A%2F%2Fabout.me
> >>>%
> >>>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%
> 7Ce35c7c474380432414130
> >>>8
> >>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C6365274012008344
> >>>6
> >>>5&sdata=3LH%2BI93bLwNWxoOGx6eo6A2MBQaxxUMrNrufjXIh6Bo%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%
> 7Ce35c7c4743804324141
> >>>3
> >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
> cee1%7C0%7C0%7C63652740120083
> >>>4
> >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%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%
> 7Ce35c7c474380432414130
> >>8
> >>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C63652740120083446
> >>5
> >>&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
>
>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Piotr Zarzycki <pi...@gmail.com>.
Yes we are agreed to use GH pages. I'm glad that is working with google,
but let's move forward with Jekyll. We have auto publications once we push
it. It is very convenient!
Thanks, Piotr
2018-01-29 8:56 GMT+01:00 Alex Harui <ah...@adobe.com.invalid>:
> I'm still confused. I think we agreed to use GH Pages. AFAICT, GH Pages
> uses Jekyll and Markdown. Jekyll expects a certain layout like templates
> in a _layout folder. I have put a template in there. I don't understand
> using a different production system that doesn't use Jekyll and its way of
> laying out text.
>
> -Alex
>
> On 1/28/18, 11:11 PM, "omuppi1@gmail.com on behalf of OmPrakash Muppirala"
> <omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>
> >This does not use the Jekyll workflow. This uses the .md files directly.
> >
> >Thanks,
> >Om
> >
> >On Jan 28, 2018 10:57 PM, "Alex Harui" <ah...@adobe.com.invalid> wrote:
> >
> >I don’t get it. There is a Jekyll template in our repo. The link I just
> >clicked on did not appear to use it.
> >
> >-Alex
> >
> >On 1/28/18, 4:41 AM, "Andrew Wetmore" <co...@gmail.com> wrote:
> >
> >>Yeah...the one thing it does not have is an expanding-collapsing ToC. The
> >>scrolling is not bad, but the intimidation effect of endless topic titles
> >>can be large. For me that is a usability negative...but not a
> >>deal-killer.
> >>
> >>On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <ha...@gmail.com>
> >>wrote:
> >>
> >>> BTW:
> >>>
> >>> That site has 3 levels in the table of contents:
> >>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fredux.j
> >>>s
> >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&
> data=02%7C0
> >>>1
> >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7b344
> >>>3
> >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=
> 4Bdy4FThikLGQukS0S
> >>>S
> >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0 <
> >>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fredux.j
> >>>s
> >>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&
> data=02%7C0
> >>>1
> >>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7b344
> >>>3
> >>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=
> 4Bdy4FThikLGQukS0S
> >>>S
> >>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0>
> >>>
> >>> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala
> >>><bi...@gmail.com>
> >>> wrote:
> >>> >
> >>> > Here is a very good example of what the end product would look like:
> >>> >
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fredux.j
> >>>s
> >>>.org%2F&data=02%7C01%7Caharui%40adobe.com%
> 7Ce35c7c4743804324141308d5664c
> >>>8
> >>>547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C636527401200834465&sdat
> >>>a
> >>>=GrTlTr5PCqHK6qS9pg9dKcKyRtO6BJU1xpxLGzWYOsY%3D&reserved=0
> >>> >
> >>> > Thanks,
> >>> > Om
> >>> >
> >>> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <
> >>> bigosmallm@gmail.com>
> >>> > wrote:
> >>> >
> >>> >>
> >>> >>
> >>> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com>
> >>> wrote:
> >>> >>
> >>> >>> Is this an additional way of viewing the content or a replacement
> >>>for
> >>> the
> >>> >>> Jenkyll-produced site?
> >>> >>>
> >>> >>> If it’s the former, I can’t see any reason why not.
> >>> >>>
> >>> >>
> >>> >> It's an additional way. It uses the .md files from the github repo
> >>>and
> >>> >> builds its own site.
> >>> >>
> >>> >> Thanks,
> >>> >> Om
> >>> >>
> >>> >>
> >>> >>>
> >>> >>> Harbs
> >>> >>>
> >>> >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <
> >>> bigosmallm@gmail.com>
> >>> >>> wrote:
> >>> >>>>
> >>> >>>> I've been playing around with the tool: GitBook
> >>>[https://na01.safelinks.protection.outlook.com/?url=
> www.gitbooks.io&data
> >>>=
> >>>02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b
> >>>5
> >>>a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&
> sdata=VI3BEHW9v7G
> >>>P
> >>>nAlTOg2gEp%2FgLrF61UFUShsrxY1wG7I%3D&reserved=0]
> >>> >>>> I was able to connect my personal fork of the royale-docs to my
> >>> >>> gitbooks.io
> >>> >>>> account. This way, all my .md files are automatically available
> >>>for
> >>> >>> Docs
> >>> >>>> creation.
> >>> >>>>
> >>> >>>> Here is an example I created in a few minutes:
> >>> >>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fbigosma
> >>>l
> >>>lm.gitbooks.io%2Froyale-docs-test2%2Fcontent%2Fv%2F&
> data=02%7C01%7Caharu
> >>>i
> >>>%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7b34438794aed2
> >>>c
> >>>178decee1%7C0%7C0%7C636527401200834465&sdata=
> wYN9q4TD9UFz8rwXmzoh8QDc16E
> >>>n
> >>>Q64NDLMa4XKvMdg%3D&reserved=0
> >>> >>> develop/Create%20An%20Application.html
> >>> >>>>
> >>> >>>> The advantages I see using this tool are:
> >>> >>>>
> >>> >>>> * Seems to be a widely used tool for documentation these days.
> >>> >>> NPMjs.org,
> >>> >>>> React, Redux, etc. use Gitbook
> >>> >>>> * Two way sync between github and gitbook app. That is, you can
> >>> create
> >>> >>> an
> >>> >>>> .md file on github and see it on gitbook. You can also create
> >>>more
> >>> >>> content
> >>> >>>> using the WYSIWYG editor on Gitbook, which will be synced to the
> >>> github
> >>> >>>> repo.
> >>> >>>> * Seems pretty straightforward to create a TOC. It includes
> >>>support
> >>> for
> >>> >>>> tree structure by default
> >>> >>>> * We can choose to use the web app on gitbook.com or use the open
> >>> >>>> source(Apache V2 licensed |
> >>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub
> .
> >>>c
> >>>om%2FGitbookIO%2Fgitbook&data=02%7C01%7Caharui%40adobe.com
> %7Ce35c7c47438
> >>>0
> >>>4324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
> cee1%7C0%7C0%7C636527
> >>>4
> >>>01200834465&sdata=9yrCy9F6C7auYCI%2FEjfdLi8gTkkma%2FN4rURUrFDU%
> 2FZI%3D&r
> >>>e
> >>>served=0)
> >>> >>> command
> >>> >>>> line tool. The CLI will help us integrate with our Jenkins build
> >>>for
> >>> >>>> example.
> >>> >>>> * Allows users to provide feedback on the site itself
> >>> >>>> * Allows us to point the docs site to our custom domain address
> >>> >>>>
> >>> >>>>
> >>> >>>> If there is more interest in trying this out, I can set up an
> >>> >>> Organization
> >>> >>>> account (free) and add users as needed.
> >>> >>>>
> >>> >>>> Thanks,
> >>> >>>> Om
> >>> >>>>
> >>> >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore
> >>><co...@gmail.com>
> >>> >>> wrote:
> >>> >>>>
> >>> >>>>> If the ToC accordions properly and we need three levels, I do not
> >>>see
> >>> >>> why
> >>> >>>>> three levels would cause more confusion than two levels. If this
> >>>is a
> >>> >>>>> resource providing information people are going to need to use
> >>> Royale,
> >>> >>> and
> >>> >>>>> if that information is not readily available elsewhere, then we
> >>> should
> >>> >>> make
> >>> >>>>> the ToC fit the information, not the other way around.
> >>> >>>>>
> >>> >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
> >>> >>> carlosrovira@apache.org>
> >>> >>>>> wrote:
> >>> >>>>>
> >>> >>>>>> Hi Alex,
> >>> >>>>>>
> >>> >>>>>> for TOC. One think that's very important to me: Please only *two
> >>> >>> levels*
> >>> >>>>> in
> >>> >>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's
> >>>the
> >>> >>>>>> standard right now and a three level only created confusion.
> >>>Again
> >>> see
> >>> >>>>>> Angular and React sites to match what they did and take it as a
> >>> >>>>> reference.
> >>> >>>>>>
> >>> >>>>>> For states. I think the trick here is that a .md page has some
> >>> >>> variables
> >>> >>>>>> that will make the right top level branch open in TOC and as
> >>>well
> >>> make
> >>> >>>>> the
> >>> >>>>>> right sub option appears as selected (strong type) and without
> >>>link.
> >>> >>> As
> >>> >>>>> we
> >>> >>>>>> are dealing with static GitHub pages I think there's no concept
> >>>of
> >>> >>>>>> component, only that all pages has the TOC added to the sidebar.
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
> >>> >>>>>>
> >>> >>>>>>> What you describe sounds fine to me. I don't think we need to
> >>>worry
> >>> >>>>> about
> >>> >>>>>>> breadcrumbs and state and helping people go backwards through
> >>>their
> >>> >>>>>> series
> >>> >>>>>>> of clicks.
> >>> >>>>>>>
> >>> >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui
> >>> <aharui@adobe.com.invalid
> >>> >>>>
> >>> >>>>>>> wrote:
> >>> >>>>>>>
> >>> >>>>>>>> Breaking out a separate thread on this...
> >>> >>>>>>>>
> >>> >>>>>>>> Thinking about this some more, I think I can generate an
> >>> interactive
> >>> >>>>>>>> control with Jekyll, but I don't know how to make it retain
> >>>state.
> >>> >>> I
> >>> >>>>>>>> think that might require cookies and/or frames.
> >>> >>>>>>>>
> >>> >>>>>>>> For example, let's say the TOC looked like:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> ----AS3
> >>> >>>>>>>> ----MXML
> >>> >>>>>>>> Get Started
> >>> >>>>>>>> --Download
> >>> >>>>>>>> --Hello World
> >>> >>>>>>>>
> >>> >>>>>>>> I've already implemented logic in the template to auto-expand
> >>>the
> >>> >>>>> tree
> >>> >>>>>> to
> >>> >>>>>>>> the document for folks who have direct links. So, if you do a
> >>> >>> Google
> >>> >>>>>>>> Search and find the link to the MXML page, when you go to that
> >>> page,
> >>> >>>>>> the
> >>> >>>>>>>> ToC will automatically look like:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> ----AS3
> >>> >>>>>>>> ---*MXML*
> >>> >>>>>>>> Get Started
> >>> >>>>>>>>
> >>> >>>>>>>>
> >>> >>>>>>>>
> >>> >>>>>>>> If you hit the main doc page, the ToC starts out collapsed so
> >>>that
> >>> >>>>> Get
> >>> >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics.
> >>>So
> >>> the
> >>> >>>>> ToC
> >>> >>>>>>>> initially looks like:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> Get Started
> >>> >>>>>>>>
> >>> >>>>>>>> Now let's say you expand both Welcome and Get Started so you
> >>>see:
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> Get Started
> >>> >>>>>>>> --Download
> >>> >>>>>>>> --Hello World
> >>> >>>>>>>>
> >>> >>>>>>>> Then you click on Features. The logic that opens trees to
> >>>direct
> >>> >>>>> links
> >>> >>>>>>> is
> >>> >>>>>>>> going to cause the ToC to look like:
> >>> >>>>>>>>
> >>> >>>>>>>>
> >>> >>>>>>>> Welcome
> >>> >>>>>>>> --High Level View
> >>> >>>>>>>> --Features
> >>> >>>>>>>> Get Started
> >>> >>>>>>>>
> >>> >>>>>>>> Even though you had expanded "Get Started" it will collapse
> >>>when
> >>> >>>>> going
> >>> >>>>>> to
> >>> >>>>>>>> the Features page. That's because, without frames, each page
> >>>is
> >>> its
> >>> >>>>>> own
> >>> >>>>>>>> HTML page. No state about the ToC is retained or shared.
> >>> >>>>>>>>
> >>> >>>>>>>> If folks are ok with that, I can probably get that to work.
> >>> >>>>>>>>
> >>> >>>>>>>> Thoughts?
> >>> >>>>>>>> -Alex
> >>> >>>>>>>>
> >>> >>>>>>> --
> >>> >>>>>>> Andrew Wetmore
> >>> >>>>>>>
> >>> >>>>>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> http%3A%2F%2Fcottage1
> >>>4
> >>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%
> 7Ce35c7c4743804324141
> >>>3
> >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
> cee1%7C0%7C0%7C63652740120083
> >>>4
> >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>> >>>>>>>
> >>><https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fwww.av
> >>>a
> >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%
> 7C01%7Caharui%40a
> >>>d
> >>>obe.com%7Ce35c7c4743804324141308d5664c8547%
> 7Cfa7b1b5a7b34438794aed2c178d
> >>>e
> >>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j
> mB
> >>>P
> >>>S86IdsRNiQ%3D&reserved=0
> >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>> >>>>>>> Virus-free.
> >>> >>>>>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> www.avast.com&data=02
> >>>%
> >>>7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
> 8547%7Cfa7b1b5a7
> >>>b
> >>>34438794aed2c178decee1%7C0%7C0%7C636527401200834465&
> sdata=zkLsd1ijA9LimW
> >>>6
> >>>%2F3Kfze8CwM%2Fn2ty8Twehti%2B8QbXA%3D&reserved=0
> >>> >>>>>>>
> >>><https://na01.safelinks.protection.outlook.com/?url=
> https%3A%2F%2Fwww.av
> >>>a
> >>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%
> 7C01%7Caharui%40a
> >>>d
> >>>obe.com%7Ce35c7c4743804324141308d5664c8547%
> 7Cfa7b1b5a7b34438794aed2c178d
> >>>e
> >>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5j
> mB
> >>>P
> >>>S86IdsRNiQ%3D&reserved=0
> >>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
> >>> >>>>>>>
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>>
> >>> >>>>>> --
> >>> >>>>>> Carlos Rovira
> >>> >>>>>>
> >>>https://na01.safelinks.protection.outlook.com/?url=
> http%3A%2F%2Fabout.me
> >>>%
> >>>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%
> 7Ce35c7c474380432414130
> >>>8
> >>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C6365274012008344
> >>>6
> >>>5&sdata=3LH%2BI93bLwNWxoOGx6eo6A2MBQaxxUMrNrufjXIh6Bo%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%
> 7Ce35c7c4743804324141
> >>>3
> >>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
> cee1%7C0%7C0%7C63652740120083
> >>>4
> >>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%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%
> 7Ce35c7c474380432414130
> >>8
> >>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%
> 7C63652740120083446
> >>5
> >>&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
>
>
--
Piotr Zarzycki
Patreon: *https://www.patreon.com/piotrzarzycki
<https://www.patreon.com/piotrzarzycki>*
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Alex Harui <ah...@adobe.com.INVALID>.
I'm still confused. I think we agreed to use GH Pages. AFAICT, GH Pages
uses Jekyll and Markdown. Jekyll expects a certain layout like templates
in a _layout folder. I have put a template in there. I don't understand
using a different production system that doesn't use Jekyll and its way of
laying out text.
-Alex
On 1/28/18, 11:11 PM, "omuppi1@gmail.com on behalf of OmPrakash Muppirala"
<omuppi1@gmail.com on behalf of bigosmallm@gmail.com> wrote:
>This does not use the Jekyll workflow. This uses the .md files directly.
>
>Thanks,
>Om
>
>On Jan 28, 2018 10:57 PM, "Alex Harui" <ah...@adobe.com.invalid> wrote:
>
>I don’t get it. There is a Jekyll template in our repo. The link I just
>clicked on did not appear to use it.
>
>-Alex
>
>On 1/28/18, 4:41 AM, "Andrew Wetmore" <co...@gmail.com> wrote:
>
>>Yeah...the one thing it does not have is an expanding-collapsing ToC. The
>>scrolling is not bad, but the intimidation effect of endless topic titles
>>can be large. For me that is a usability negative...but not a
>>deal-killer.
>>
>>On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <ha...@gmail.com>
>>wrote:
>>
>>> BTW:
>>>
>>> That site has 3 levels in the table of contents:
>>>
>>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.j
>>>s
>>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&data=02%7C0
>>>1
>>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b344
>>>3
>>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=4Bdy4FThikLGQukS0S
>>>S
>>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0 <
>>>
>>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.j
>>>s
>>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&data=02%7C0
>>>1
>>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b344
>>>3
>>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=4Bdy4FThikLGQukS0S
>>>S
>>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0>
>>>
>>> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala
>>><bi...@gmail.com>
>>> wrote:
>>> >
>>> > Here is a very good example of what the end product would look like:
>>> >
>>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.j
>>>s
>>>.org%2F&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c
>>>8
>>>547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdat
>>>a
>>>=GrTlTr5PCqHK6qS9pg9dKcKyRtO6BJU1xpxLGzWYOsY%3D&reserved=0
>>> >
>>> > Thanks,
>>> > Om
>>> >
>>> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <
>>> bigosmallm@gmail.com>
>>> > wrote:
>>> >
>>> >>
>>> >>
>>> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com>
>>> wrote:
>>> >>
>>> >>> Is this an additional way of viewing the content or a replacement
>>>for
>>> the
>>> >>> Jenkyll-produced site?
>>> >>>
>>> >>> If it’s the former, I can’t see any reason why not.
>>> >>>
>>> >>
>>> >> It's an additional way. It uses the .md files from the github repo
>>>and
>>> >> builds its own site.
>>> >>
>>> >> Thanks,
>>> >> Om
>>> >>
>>> >>
>>> >>>
>>> >>> Harbs
>>> >>>
>>> >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <
>>> bigosmallm@gmail.com>
>>> >>> wrote:
>>> >>>>
>>> >>>> I've been playing around with the tool: GitBook
>>>[https://na01.safelinks.protection.outlook.com/?url=www.gitbooks.io&data
>>>=
>>>02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b
>>>5
>>>a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=VI3BEHW9v7G
>>>P
>>>nAlTOg2gEp%2FgLrF61UFUShsrxY1wG7I%3D&reserved=0]
>>> >>>> I was able to connect my personal fork of the royale-docs to my
>>> >>> gitbooks.io
>>> >>>> account. This way, all my .md files are automatically available
>>>for
>>> >>> Docs
>>> >>>> creation.
>>> >>>>
>>> >>>> Here is an example I created in a few minutes:
>>> >>>>
>>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbigosma
>>>l
>>>lm.gitbooks.io%2Froyale-docs-test2%2Fcontent%2Fv%2F&data=02%7C01%7Caharu
>>>i
>>>%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2
>>>c
>>>178decee1%7C0%7C0%7C636527401200834465&sdata=wYN9q4TD9UFz8rwXmzoh8QDc16E
>>>n
>>>Q64NDLMa4XKvMdg%3D&reserved=0
>>> >>> develop/Create%20An%20Application.html
>>> >>>>
>>> >>>> The advantages I see using this tool are:
>>> >>>>
>>> >>>> * Seems to be a widely used tool for documentation these days.
>>> >>> NPMjs.org,
>>> >>>> React, Redux, etc. use Gitbook
>>> >>>> * Two way sync between github and gitbook app. That is, you can
>>> create
>>> >>> an
>>> >>>> .md file on github and see it on gitbook. You can also create
>>>more
>>> >>> content
>>> >>>> using the WYSIWYG editor on Gitbook, which will be synced to the
>>> github
>>> >>>> repo.
>>> >>>> * Seems pretty straightforward to create a TOC. It includes
>>>support
>>> for
>>> >>>> tree structure by default
>>> >>>> * We can choose to use the web app on gitbook.com or use the open
>>> >>>> source(Apache V2 licensed |
>>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.
>>>c
>>>om%2FGitbookIO%2Fgitbook&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c47438
>>>0
>>>4324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527
>>>4
>>>01200834465&sdata=9yrCy9F6C7auYCI%2FEjfdLi8gTkkma%2FN4rURUrFDU%2FZI%3D&r
>>>e
>>>served=0)
>>> >>> command
>>> >>>> line tool. The CLI will help us integrate with our Jenkins build
>>>for
>>> >>>> example.
>>> >>>> * Allows users to provide feedback on the site itself
>>> >>>> * Allows us to point the docs site to our custom domain address
>>> >>>>
>>> >>>>
>>> >>>> If there is more interest in trying this out, I can set up an
>>> >>> Organization
>>> >>>> account (free) and add users as needed.
>>> >>>>
>>> >>>> Thanks,
>>> >>>> Om
>>> >>>>
>>> >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore
>>><co...@gmail.com>
>>> >>> wrote:
>>> >>>>
>>> >>>>> If the ToC accordions properly and we need three levels, I do not
>>>see
>>> >>> why
>>> >>>>> three levels would cause more confusion than two levels. If this
>>>is a
>>> >>>>> resource providing information people are going to need to use
>>> Royale,
>>> >>> and
>>> >>>>> if that information is not readily available elsewhere, then we
>>> should
>>> >>> make
>>> >>>>> the ToC fit the information, not the other way around.
>>> >>>>>
>>> >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
>>> >>> carlosrovira@apache.org>
>>> >>>>> wrote:
>>> >>>>>
>>> >>>>>> Hi Alex,
>>> >>>>>>
>>> >>>>>> for TOC. One think that's very important to me: Please only *two
>>> >>> levels*
>>> >>>>> in
>>> >>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's
>>>the
>>> >>>>>> standard right now and a three level only created confusion.
>>>Again
>>> see
>>> >>>>>> Angular and React sites to match what they did and take it as a
>>> >>>>> reference.
>>> >>>>>>
>>> >>>>>> For states. I think the trick here is that a .md page has some
>>> >>> variables
>>> >>>>>> that will make the right top level branch open in TOC and as
>>>well
>>> make
>>> >>>>> the
>>> >>>>>> right sub option appears as selected (strong type) and without
>>>link.
>>> >>> As
>>> >>>>> we
>>> >>>>>> are dealing with static GitHub pages I think there's no concept
>>>of
>>> >>>>>> component, only that all pages has the TOC added to the sidebar.
>>> >>>>>>
>>> >>>>>>
>>> >>>>>>
>>> >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>>> >>>>>>
>>> >>>>>>> What you describe sounds fine to me. I don't think we need to
>>>worry
>>> >>>>> about
>>> >>>>>>> breadcrumbs and state and helping people go backwards through
>>>their
>>> >>>>>> series
>>> >>>>>>> of clicks.
>>> >>>>>>>
>>> >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui
>>> <aharui@adobe.com.invalid
>>> >>>>
>>> >>>>>>> wrote:
>>> >>>>>>>
>>> >>>>>>>> Breaking out a separate thread on this...
>>> >>>>>>>>
>>> >>>>>>>> Thinking about this some more, I think I can generate an
>>> interactive
>>> >>>>>>>> control with Jekyll, but I don't know how to make it retain
>>>state.
>>> >>> I
>>> >>>>>>>> think that might require cookies and/or frames.
>>> >>>>>>>>
>>> >>>>>>>> For example, let's say the TOC looked like:
>>> >>>>>>>>
>>> >>>>>>>> Welcome
>>> >>>>>>>> --High Level View
>>> >>>>>>>> --Features
>>> >>>>>>>> ----AS3
>>> >>>>>>>> ----MXML
>>> >>>>>>>> Get Started
>>> >>>>>>>> --Download
>>> >>>>>>>> --Hello World
>>> >>>>>>>>
>>> >>>>>>>> I've already implemented logic in the template to auto-expand
>>>the
>>> >>>>> tree
>>> >>>>>> to
>>> >>>>>>>> the document for folks who have direct links. So, if you do a
>>> >>> Google
>>> >>>>>>>> Search and find the link to the MXML page, when you go to that
>>> page,
>>> >>>>>> the
>>> >>>>>>>> ToC will automatically look like:
>>> >>>>>>>>
>>> >>>>>>>> Welcome
>>> >>>>>>>> --High Level View
>>> >>>>>>>> --Features
>>> >>>>>>>> ----AS3
>>> >>>>>>>> ---*MXML*
>>> >>>>>>>> Get Started
>>> >>>>>>>>
>>> >>>>>>>>
>>> >>>>>>>>
>>> >>>>>>>> If you hit the main doc page, the ToC starts out collapsed so
>>>that
>>> >>>>> Get
>>> >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics.
>>>So
>>> the
>>> >>>>> ToC
>>> >>>>>>>> initially looks like:
>>> >>>>>>>>
>>> >>>>>>>> Welcome
>>> >>>>>>>> Get Started
>>> >>>>>>>>
>>> >>>>>>>> Now let's say you expand both Welcome and Get Started so you
>>>see:
>>> >>>>>>>>
>>> >>>>>>>> Welcome
>>> >>>>>>>> --High Level View
>>> >>>>>>>> --Features
>>> >>>>>>>> Get Started
>>> >>>>>>>> --Download
>>> >>>>>>>> --Hello World
>>> >>>>>>>>
>>> >>>>>>>> Then you click on Features. The logic that opens trees to
>>>direct
>>> >>>>> links
>>> >>>>>>> is
>>> >>>>>>>> going to cause the ToC to look like:
>>> >>>>>>>>
>>> >>>>>>>>
>>> >>>>>>>> Welcome
>>> >>>>>>>> --High Level View
>>> >>>>>>>> --Features
>>> >>>>>>>> Get Started
>>> >>>>>>>>
>>> >>>>>>>> Even though you had expanded "Get Started" it will collapse
>>>when
>>> >>>>> going
>>> >>>>>> to
>>> >>>>>>>> the Features page. That's because, without frames, each page
>>>is
>>> its
>>> >>>>>> own
>>> >>>>>>>> HTML page. No state about the ToC is retained or shared.
>>> >>>>>>>>
>>> >>>>>>>> If folks are ok with that, I can probably get that to work.
>>> >>>>>>>>
>>> >>>>>>>> Thoughts?
>>> >>>>>>>> -Alex
>>> >>>>>>>>
>>> >>>>>>> --
>>> >>>>>>> Andrew Wetmore
>>> >>>>>>>
>>> >>>>>>>
>>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage1
>>>4
>>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141
>>>3
>>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C63652740120083
>>>4
>>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
>>> >>>>>>>
>>> >>>>>>>
>>> >>>>>>>
>>> >>>>>>>
>>> >>>>>>>
>>> >>>>>>>
>>><https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.av
>>>a
>>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%7C01%7Caharui%40a
>>>d
>>>obe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178d
>>>e
>>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5jmB
>>>P
>>>S86IdsRNiQ%3D&reserved=0
>>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>> >>>>>>> Virus-free.
>>> >>>>>>>
>>>https://na01.safelinks.protection.outlook.com/?url=www.avast.com&data=02
>>>%
>>>7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7
>>>b
>>>34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=zkLsd1ijA9LimW
>>>6
>>>%2F3Kfze8CwM%2Fn2ty8Twehti%2B8QbXA%3D&reserved=0
>>> >>>>>>>
>>><https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.av
>>>a
>>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%7C01%7Caharui%40a
>>>d
>>>obe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178d
>>>e
>>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5jmB
>>>P
>>>S86IdsRNiQ%3D&reserved=0
>>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>>> >>>>>>>
>>> >>>>>>
>>> >>>>>>
>>> >>>>>>
>>> >>>>>> --
>>> >>>>>> Carlos Rovira
>>> >>>>>>
>>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me
>>>%
>>>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c474380432414130
>>>8
>>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C6365274012008344
>>>6
>>>5&sdata=3LH%2BI93bLwNWxoOGx6eo6A2MBQaxxUMrNrufjXIh6Bo%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%7Ce35c7c4743804324141
>>>3
>>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C63652740120083
>>>4
>>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%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%7Ce35c7c474380432414130
>>8
>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C63652740120083446
>>5
>>&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by OmPrakash Muppirala <bi...@gmail.com>.
This does not use the Jekyll workflow. This uses the .md files directly.
Thanks,
Om
On Jan 28, 2018 10:57 PM, "Alex Harui" <ah...@adobe.com.invalid> wrote:
I don’t get it. There is a Jekyll template in our repo. The link I just
clicked on did not appear to use it.
-Alex
On 1/28/18, 4:41 AM, "Andrew Wetmore" <co...@gmail.com> wrote:
>Yeah...the one thing it does not have is an expanding-collapsing ToC. The
>scrolling is not bad, but the intimidation effect of endless topic titles
>can be large. For me that is a usability negative...but not a deal-killer.
>
>On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <ha...@gmail.com> wrote:
>
>> BTW:
>>
>> That site has 3 levels in the table of contents:
>>
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.js
>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&data=02%7C01
>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b3443
>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=4Bdy4FThikLGQukS0SS
>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0 <
>>
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.js
>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&data=02%7C01
>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b3443
>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=4Bdy4FThikLGQukS0SS
>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0>
>>
>> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala
>><bi...@gmail.com>
>> wrote:
>> >
>> > Here is a very good example of what the end product would look like:
>> >
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.js
>>.org%2F&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8
>>547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata
>>=GrTlTr5PCqHK6qS9pg9dKcKyRtO6BJU1xpxLGzWYOsY%3D&reserved=0
>> >
>> > Thanks,
>> > Om
>> >
>> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <
>> bigosmallm@gmail.com>
>> > wrote:
>> >
>> >>
>> >>
>> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com>
>> wrote:
>> >>
>> >>> Is this an additional way of viewing the content or a replacement
>>for
>> the
>> >>> Jenkyll-produced site?
>> >>>
>> >>> If it’s the former, I can’t see any reason why not.
>> >>>
>> >>
>> >> It's an additional way. It uses the .md files from the github repo
>>and
>> >> builds its own site.
>> >>
>> >> Thanks,
>> >> Om
>> >>
>> >>
>> >>>
>> >>> Harbs
>> >>>
>> >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <
>> bigosmallm@gmail.com>
>> >>> wrote:
>> >>>>
>> >>>> I've been playing around with the tool: GitBook
>>[https://na01.safelinks.protection.outlook.com/?url=www.gitbooks.io&data=
>>02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5
>>a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=VI3BEHW9v7GP
>>nAlTOg2gEp%2FgLrF61UFUShsrxY1wG7I%3D&reserved=0]
>> >>>> I was able to connect my personal fork of the royale-docs to my
>> >>> gitbooks.io
>> >>>> account. This way, all my .md files are automatically available
>>for
>> >>> Docs
>> >>>> creation.
>> >>>>
>> >>>> Here is an example I created in a few minutes:
>> >>>>
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbigosmal
>>lm.gitbooks.io%2Froyale-docs-test2%2Fcontent%2Fv%2F&data=02%7C01%7Caharui
>>%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c
>>178decee1%7C0%7C0%7C636527401200834465&sdata=wYN9q4TD9UFz8rwXmzoh8QDc16En
>>Q64NDLMa4XKvMdg%3D&reserved=0
>> >>> develop/Create%20An%20Application.html
>> >>>>
>> >>>> The advantages I see using this tool are:
>> >>>>
>> >>>> * Seems to be a widely used tool for documentation these days.
>> >>> NPMjs.org,
>> >>>> React, Redux, etc. use Gitbook
>> >>>> * Two way sync between github and gitbook app. That is, you can
>> create
>> >>> an
>> >>>> .md file on github and see it on gitbook. You can also create more
>> >>> content
>> >>>> using the WYSIWYG editor on Gitbook, which will be synced to the
>> github
>> >>>> repo.
>> >>>> * Seems pretty straightforward to create a TOC. It includes
>>support
>> for
>> >>>> tree structure by default
>> >>>> * We can choose to use the web app on gitbook.com or use the open
>> >>>> source(Apache V2 licensed |
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.c
>>om%2FGitbookIO%2Fgitbook&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c474380
>>4324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C6365274
>>01200834465&sdata=9yrCy9F6C7auYCI%2FEjfdLi8gTkkma%2FN4rURUrFDU%2FZI%3D&re
>>served=0)
>> >>> command
>> >>>> line tool. The CLI will help us integrate with our Jenkins build
>>for
>> >>>> example.
>> >>>> * Allows users to provide feedback on the site itself
>> >>>> * Allows us to point the docs site to our custom domain address
>> >>>>
>> >>>>
>> >>>> If there is more interest in trying this out, I can set up an
>> >>> Organization
>> >>>> account (free) and add users as needed.
>> >>>>
>> >>>> Thanks,
>> >>>> Om
>> >>>>
>> >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore
>><co...@gmail.com>
>> >>> wrote:
>> >>>>
>> >>>>> If the ToC accordions properly and we need three levels, I do not
>>see
>> >>> why
>> >>>>> three levels would cause more confusion than two levels. If this
>>is a
>> >>>>> resource providing information people are going to need to use
>> Royale,
>> >>> and
>> >>>>> if that information is not readily available elsewhere, then we
>> should
>> >>> make
>> >>>>> the ToC fit the information, not the other way around.
>> >>>>>
>> >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
>> >>> carlosrovira@apache.org>
>> >>>>> wrote:
>> >>>>>
>> >>>>>> Hi Alex,
>> >>>>>>
>> >>>>>> for TOC. One think that's very important to me: Please only *two
>> >>> levels*
>> >>>>> in
>> >>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's
>>the
>> >>>>>> standard right now and a three level only created confusion.
>>Again
>> see
>> >>>>>> Angular and React sites to match what they did and take it as a
>> >>>>> reference.
>> >>>>>>
>> >>>>>> For states. I think the trick here is that a .md page has some
>> >>> variables
>> >>>>>> that will make the right top level branch open in TOC and as well
>> make
>> >>>>> the
>> >>>>>> right sub option appears as selected (strong type) and without
>>link.
>> >>> As
>> >>>>> we
>> >>>>>> are dealing with static GitHub pages I think there's no concept
>>of
>> >>>>>> component, only that all pages has the TOC added to the sidebar.
>> >>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>> >>>>>>
>> >>>>>>> What you describe sounds fine to me. I don't think we need to
>>worry
>> >>>>> about
>> >>>>>>> breadcrumbs and state and helping people go backwards through
>>their
>> >>>>>> series
>> >>>>>>> of clicks.
>> >>>>>>>
>> >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui
>> <aharui@adobe.com.invalid
>> >>>>
>> >>>>>>> wrote:
>> >>>>>>>
>> >>>>>>>> Breaking out a separate thread on this...
>> >>>>>>>>
>> >>>>>>>> Thinking about this some more, I think I can generate an
>> interactive
>> >>>>>>>> control with Jekyll, but I don't know how to make it retain
>>state.
>> >>> I
>> >>>>>>>> think that might require cookies and/or frames.
>> >>>>>>>>
>> >>>>>>>> For example, let's say the TOC looked like:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> ----AS3
>> >>>>>>>> ----MXML
>> >>>>>>>> Get Started
>> >>>>>>>> --Download
>> >>>>>>>> --Hello World
>> >>>>>>>>
>> >>>>>>>> I've already implemented logic in the template to auto-expand
>>the
>> >>>>> tree
>> >>>>>> to
>> >>>>>>>> the document for folks who have direct links. So, if you do a
>> >>> Google
>> >>>>>>>> Search and find the link to the MXML page, when you go to that
>> page,
>> >>>>>> the
>> >>>>>>>> ToC will automatically look like:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> ----AS3
>> >>>>>>>> ---*MXML*
>> >>>>>>>> Get Started
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>> If you hit the main doc page, the ToC starts out collapsed so
>>that
>> >>>>> Get
>> >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So
>> the
>> >>>>> ToC
>> >>>>>>>> initially looks like:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> Get Started
>> >>>>>>>>
>> >>>>>>>> Now let's say you expand both Welcome and Get Started so you
>>see:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> Get Started
>> >>>>>>>> --Download
>> >>>>>>>> --Hello World
>> >>>>>>>>
>> >>>>>>>> Then you click on Features. The logic that opens trees to
>>direct
>> >>>>> links
>> >>>>>>> is
>> >>>>>>>> going to cause the ToC to look like:
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> Get Started
>> >>>>>>>>
>> >>>>>>>> Even though you had expanded "Get Started" it will collapse
>>when
>> >>>>> going
>> >>>>>> to
>> >>>>>>>> the Features page. That's because, without frames, each page
>>is
>> its
>> >>>>>> own
>> >>>>>>>> HTML page. No state about the ToC is retained or shared.
>> >>>>>>>>
>> >>>>>>>> If folks are ok with that, I can probably get that to work.
>> >>>>>>>>
>> >>>>>>>> Thoughts?
>> >>>>>>>> -Alex
>> >>>>>>>>
>> >>>>>>> --
>> >>>>>>> Andrew Wetmore
>> >>>>>>>
>> >>>>>>>
>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14
>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c47438043241413
>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834
>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>><https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ava
>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%7C01%7Caharui%40ad
>>obe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5jmBP
>>S86IdsRNiQ%3D&reserved=0
>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>>>>>> Virus-free.
>> >>>>>>>
>>https://na01.safelinks.protection.outlook.com/?url=www.avast.com&data=02%
>>7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b
>>34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=zkLsd1ijA9LimW6
>>%2F3Kfze8CwM%2Fn2ty8Twehti%2B8QbXA%3D&reserved=0
>> >>>>>>>
>><https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ava
>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%7C01%7Caharui%40ad
>>obe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5jmBP
>>S86IdsRNiQ%3D&reserved=0
>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>> >>>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>> --
>> >>>>>> Carlos Rovira
>> >>>>>>
>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%
>>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308
>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C63652740120083446
>>5&sdata=3LH%2BI93bLwNWxoOGx6eo6A2MBQaxxUMrNrufjXIh6Bo%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%7Ce35c7c47438043241413
>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834
>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%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%7Ce35c7c4743804324141308
>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465
>&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Alex Harui <ah...@adobe.com.INVALID>.
I don’t get it. There is a Jekyll template in our repo. The link I just
clicked on did not appear to use it.
-Alex
On 1/28/18, 4:41 AM, "Andrew Wetmore" <co...@gmail.com> wrote:
>Yeah...the one thing it does not have is an expanding-collapsing ToC. The
>scrolling is not bad, but the intimidation effect of endless topic titles
>can be large. For me that is a usability negative...but not a deal-killer.
>
>On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <ha...@gmail.com> wrote:
>
>> BTW:
>>
>> That site has 3 levels in the table of contents:
>>
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.js
>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&data=02%7C01
>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b3443
>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=4Bdy4FThikLGQukS0SS
>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0 <
>>
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.js
>>.org%2Fdocs%2Frecipes%2Freducers%2FPrerequisiteConcepts.html&data=02%7C01
>>%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b3443
>>8794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=4Bdy4FThikLGQukS0SS
>>d6DXKBbnoe0oMuSrJ%2BpxpHYw%3D&reserved=0>
>>
>> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala
>><bi...@gmail.com>
>> wrote:
>> >
>> > Here is a very good example of what the end product would look like:
>> >
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fredux.js
>>.org%2F&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8
>>547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata
>>=GrTlTr5PCqHK6qS9pg9dKcKyRtO6BJU1xpxLGzWYOsY%3D&reserved=0
>> >
>> > Thanks,
>> > Om
>> >
>> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <
>> bigosmallm@gmail.com>
>> > wrote:
>> >
>> >>
>> >>
>> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com>
>> wrote:
>> >>
>> >>> Is this an additional way of viewing the content or a replacement
>>for
>> the
>> >>> Jenkyll-produced site?
>> >>>
>> >>> If it’s the former, I can’t see any reason why not.
>> >>>
>> >>
>> >> It's an additional way. It uses the .md files from the github repo
>>and
>> >> builds its own site.
>> >>
>> >> Thanks,
>> >> Om
>> >>
>> >>
>> >>>
>> >>> Harbs
>> >>>
>> >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <
>> bigosmallm@gmail.com>
>> >>> wrote:
>> >>>>
>> >>>> I've been playing around with the tool: GitBook
>>[https://na01.safelinks.protection.outlook.com/?url=www.gitbooks.io&data=
>>02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5
>>a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=VI3BEHW9v7GP
>>nAlTOg2gEp%2FgLrF61UFUShsrxY1wG7I%3D&reserved=0]
>> >>>> I was able to connect my personal fork of the royale-docs to my
>> >>> gitbooks.io
>> >>>> account. This way, all my .md files are automatically available
>>for
>> >>> Docs
>> >>>> creation.
>> >>>>
>> >>>> Here is an example I created in a few minutes:
>> >>>>
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbigosmal
>>lm.gitbooks.io%2Froyale-docs-test2%2Fcontent%2Fv%2F&data=02%7C01%7Caharui
>>%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c
>>178decee1%7C0%7C0%7C636527401200834465&sdata=wYN9q4TD9UFz8rwXmzoh8QDc16En
>>Q64NDLMa4XKvMdg%3D&reserved=0
>> >>> develop/Create%20An%20Application.html
>> >>>>
>> >>>> The advantages I see using this tool are:
>> >>>>
>> >>>> * Seems to be a widely used tool for documentation these days.
>> >>> NPMjs.org,
>> >>>> React, Redux, etc. use Gitbook
>> >>>> * Two way sync between github and gitbook app. That is, you can
>> create
>> >>> an
>> >>>> .md file on github and see it on gitbook. You can also create more
>> >>> content
>> >>>> using the WYSIWYG editor on Gitbook, which will be synced to the
>> github
>> >>>> repo.
>> >>>> * Seems pretty straightforward to create a TOC. It includes
>>support
>> for
>> >>>> tree structure by default
>> >>>> * We can choose to use the web app on gitbook.com or use the open
>> >>>> source(Apache V2 licensed |
>>https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.c
>>om%2FGitbookIO%2Fgitbook&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c474380
>>4324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C6365274
>>01200834465&sdata=9yrCy9F6C7auYCI%2FEjfdLi8gTkkma%2FN4rURUrFDU%2FZI%3D&re
>>served=0)
>> >>> command
>> >>>> line tool. The CLI will help us integrate with our Jenkins build
>>for
>> >>>> example.
>> >>>> * Allows users to provide feedback on the site itself
>> >>>> * Allows us to point the docs site to our custom domain address
>> >>>>
>> >>>>
>> >>>> If there is more interest in trying this out, I can set up an
>> >>> Organization
>> >>>> account (free) and add users as needed.
>> >>>>
>> >>>> Thanks,
>> >>>> Om
>> >>>>
>> >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore
>><co...@gmail.com>
>> >>> wrote:
>> >>>>
>> >>>>> If the ToC accordions properly and we need three levels, I do not
>>see
>> >>> why
>> >>>>> three levels would cause more confusion than two levels. If this
>>is a
>> >>>>> resource providing information people are going to need to use
>> Royale,
>> >>> and
>> >>>>> if that information is not readily available elsewhere, then we
>> should
>> >>> make
>> >>>>> the ToC fit the information, not the other way around.
>> >>>>>
>> >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
>> >>> carlosrovira@apache.org>
>> >>>>> wrote:
>> >>>>>
>> >>>>>> Hi Alex,
>> >>>>>>
>> >>>>>> for TOC. One think that's very important to me: Please only *two
>> >>> levels*
>> >>>>> in
>> >>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's
>>the
>> >>>>>> standard right now and a three level only created confusion.
>>Again
>> see
>> >>>>>> Angular and React sites to match what they did and take it as a
>> >>>>> reference.
>> >>>>>>
>> >>>>>> For states. I think the trick here is that a .md page has some
>> >>> variables
>> >>>>>> that will make the right top level branch open in TOC and as well
>> make
>> >>>>> the
>> >>>>>> right sub option appears as selected (strong type) and without
>>link.
>> >>> As
>> >>>>> we
>> >>>>>> are dealing with static GitHub pages I think there's no concept
>>of
>> >>>>>> component, only that all pages has the TOC added to the sidebar.
>> >>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>> >>>>>>
>> >>>>>>> What you describe sounds fine to me. I don't think we need to
>>worry
>> >>>>> about
>> >>>>>>> breadcrumbs and state and helping people go backwards through
>>their
>> >>>>>> series
>> >>>>>>> of clicks.
>> >>>>>>>
>> >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui
>> <aharui@adobe.com.invalid
>> >>>>
>> >>>>>>> wrote:
>> >>>>>>>
>> >>>>>>>> Breaking out a separate thread on this...
>> >>>>>>>>
>> >>>>>>>> Thinking about this some more, I think I can generate an
>> interactive
>> >>>>>>>> control with Jekyll, but I don't know how to make it retain
>>state.
>> >>> I
>> >>>>>>>> think that might require cookies and/or frames.
>> >>>>>>>>
>> >>>>>>>> For example, let's say the TOC looked like:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> ----AS3
>> >>>>>>>> ----MXML
>> >>>>>>>> Get Started
>> >>>>>>>> --Download
>> >>>>>>>> --Hello World
>> >>>>>>>>
>> >>>>>>>> I've already implemented logic in the template to auto-expand
>>the
>> >>>>> tree
>> >>>>>> to
>> >>>>>>>> the document for folks who have direct links. So, if you do a
>> >>> Google
>> >>>>>>>> Search and find the link to the MXML page, when you go to that
>> page,
>> >>>>>> the
>> >>>>>>>> ToC will automatically look like:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> ----AS3
>> >>>>>>>> ---*MXML*
>> >>>>>>>> Get Started
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>> If you hit the main doc page, the ToC starts out collapsed so
>>that
>> >>>>> Get
>> >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So
>> the
>> >>>>> ToC
>> >>>>>>>> initially looks like:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> Get Started
>> >>>>>>>>
>> >>>>>>>> Now let's say you expand both Welcome and Get Started so you
>>see:
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> Get Started
>> >>>>>>>> --Download
>> >>>>>>>> --Hello World
>> >>>>>>>>
>> >>>>>>>> Then you click on Features. The logic that opens trees to
>>direct
>> >>>>> links
>> >>>>>>> is
>> >>>>>>>> going to cause the ToC to look like:
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>> Welcome
>> >>>>>>>> --High Level View
>> >>>>>>>> --Features
>> >>>>>>>> Get Started
>> >>>>>>>>
>> >>>>>>>> Even though you had expanded "Get Started" it will collapse
>>when
>> >>>>> going
>> >>>>>> to
>> >>>>>>>> the Features page. That's because, without frames, each page
>>is
>> its
>> >>>>>> own
>> >>>>>>>> HTML page. No state about the ToC is retained or shared.
>> >>>>>>>>
>> >>>>>>>> If folks are ok with that, I can probably get that to work.
>> >>>>>>>>
>> >>>>>>>> Thoughts?
>> >>>>>>>> -Alex
>> >>>>>>>>
>> >>>>>>> --
>> >>>>>>> Andrew Wetmore
>> >>>>>>>
>> >>>>>>>
>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14
>>.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c47438043241413
>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834
>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>><https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ava
>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%7C01%7Caharui%40ad
>>obe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5jmBP
>>S86IdsRNiQ%3D&reserved=0
>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>>>>>> Virus-free.
>> >>>>>>>
>>https://na01.safelinks.protection.outlook.com/?url=www.avast.com&data=02%
>>7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b
>>34438794aed2c178decee1%7C0%7C0%7C636527401200834465&sdata=zkLsd1ijA9LimW6
>>%2F3Kfze8CwM%2Fn2ty8Twehti%2B8QbXA%3D&reserved=0
>> >>>>>>>
>><https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ava
>>st.com%2Fsig-email%3Futm_medium%3Demail%26utm_&data=02%7C01%7Caharui%40ad
>>obe.com%7Ce35c7c4743804324141308d5664c8547%7Cfa7b1b5a7b34438794aed2c178de
>>cee1%7C0%7C0%7C636527401200834465&sdata=zP1hihlDGyvPE2lzWpnE1jpXGWHd5jmBP
>>S86IdsRNiQ%3D&reserved=0
>> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>> >>>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>> --
>> >>>>>> Carlos Rovira
>> >>>>>>
>>https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%
>>2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Ce35c7c4743804324141308
>>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C63652740120083446
>>5&sdata=3LH%2BI93bLwNWxoOGx6eo6A2MBQaxxUMrNrufjXIh6Bo%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%7Ce35c7c47438043241413
>>08d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834
>>465&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%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%7Ce35c7c4743804324141308
>d5664c8547%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636527401200834465
>&sdata=DPIsxP2DciUYv0CdYmT%2BEqj7d7RmPAZpeNk6QD4VxcM%3D&reserved=0
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Andrew Wetmore <co...@gmail.com>.
Yeah...the one thing it does not have is an expanding-collapsing ToC. The
scrolling is not bad, but the intimidation effect of endless topic titles
can be large. For me that is a usability negative...but not a deal-killer.
On Sun, Jan 28, 2018 at 7:35 AM, Gabe Harbs <ha...@gmail.com> wrote:
> BTW:
>
> That site has 3 levels in the table of contents:
> https://redux.js.org/docs/recipes/reducers/PrerequisiteConcepts.html <
> https://redux.js.org/docs/recipes/reducers/PrerequisiteConcepts.html>
>
> > On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala <bi...@gmail.com>
> wrote:
> >
> > Here is a very good example of what the end product would look like:
> > https://redux.js.org/
> >
> > Thanks,
> > Om
> >
> > On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <
> bigosmallm@gmail.com>
> > wrote:
> >
> >>
> >>
> >> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com>
> wrote:
> >>
> >>> Is this an additional way of viewing the content or a replacement for
> the
> >>> Jenkyll-produced site?
> >>>
> >>> If it’s the former, I can’t see any reason why not.
> >>>
> >>
> >> It's an additional way. It uses the .md files from the github repo and
> >> builds its own site.
> >>
> >> Thanks,
> >> Om
> >>
> >>
> >>>
> >>> Harbs
> >>>
> >>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <
> bigosmallm@gmail.com>
> >>> wrote:
> >>>>
> >>>> I've been playing around with the tool: GitBook [www.gitbooks.io]
> >>>> I was able to connect my personal fork of the royale-docs to my
> >>> gitbooks.io
> >>>> account. This way, all my .md files are automatically available for
> >>> Docs
> >>>> creation.
> >>>>
> >>>> Here is an example I created in a few minutes:
> >>>> https://bigosmallm.gitbooks.io/royale-docs-test2/content/v/
> >>> develop/Create%20An%20Application.html
> >>>>
> >>>> The advantages I see using this tool are:
> >>>>
> >>>> * Seems to be a widely used tool for documentation these days.
> >>> NPMjs.org,
> >>>> React, Redux, etc. use Gitbook
> >>>> * Two way sync between github and gitbook app. That is, you can
> create
> >>> an
> >>>> .md file on github and see it on gitbook. You can also create more
> >>> content
> >>>> using the WYSIWYG editor on Gitbook, which will be synced to the
> github
> >>>> repo.
> >>>> * Seems pretty straightforward to create a TOC. It includes support
> for
> >>>> tree structure by default
> >>>> * We can choose to use the web app on gitbook.com or use the open
> >>>> source(Apache V2 licensed | https://github.com/GitbookIO/gitbook)
> >>> command
> >>>> line tool. The CLI will help us integrate with our Jenkins build for
> >>>> example.
> >>>> * Allows users to provide feedback on the site itself
> >>>> * Allows us to point the docs site to our custom domain address
> >>>>
> >>>>
> >>>> If there is more interest in trying this out, I can set up an
> >>> Organization
> >>>> account (free) and add users as needed.
> >>>>
> >>>> Thanks,
> >>>> Om
> >>>>
> >>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <co...@gmail.com>
> >>> wrote:
> >>>>
> >>>>> If the ToC accordions properly and we need three levels, I do not see
> >>> why
> >>>>> three levels would cause more confusion than two levels. If this is a
> >>>>> resource providing information people are going to need to use
> Royale,
> >>> and
> >>>>> if that information is not readily available elsewhere, then we
> should
> >>> make
> >>>>> the ToC fit the information, not the other way around.
> >>>>>
> >>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
> >>> carlosrovira@apache.org>
> >>>>> wrote:
> >>>>>
> >>>>>> Hi Alex,
> >>>>>>
> >>>>>> for TOC. One think that's very important to me: Please only *two
> >>> levels*
> >>>>> in
> >>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's the
> >>>>>> standard right now and a three level only created confusion. Again
> see
> >>>>>> Angular and React sites to match what they did and take it as a
> >>>>> reference.
> >>>>>>
> >>>>>> For states. I think the trick here is that a .md page has some
> >>> variables
> >>>>>> that will make the right top level branch open in TOC and as well
> make
> >>>>> the
> >>>>>> right sub option appears as selected (strong type) and without link.
> >>> As
> >>>>> we
> >>>>>> are dealing with static GitHub pages I think there's no concept of
> >>>>>> component, only that all pages has the TOC added to the sidebar.
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
> >>>>>>
> >>>>>>> What you describe sounds fine to me. I don't think we need to worry
> >>>>> about
> >>>>>>> breadcrumbs and state and helping people go backwards through their
> >>>>>> series
> >>>>>>> of clicks.
> >>>>>>>
> >>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui
> <aharui@adobe.com.invalid
> >>>>
> >>>>>>> wrote:
> >>>>>>>
> >>>>>>>> Breaking out a separate thread on this...
> >>>>>>>>
> >>>>>>>> Thinking about this some more, I think I can generate an
> interactive
> >>>>>>>> control with Jekyll, but I don't know how to make it retain state.
> >>> I
> >>>>>>>> think that might require cookies and/or frames.
> >>>>>>>>
> >>>>>>>> For example, let's say the TOC looked like:
> >>>>>>>>
> >>>>>>>> Welcome
> >>>>>>>> --High Level View
> >>>>>>>> --Features
> >>>>>>>> ----AS3
> >>>>>>>> ----MXML
> >>>>>>>> Get Started
> >>>>>>>> --Download
> >>>>>>>> --Hello World
> >>>>>>>>
> >>>>>>>> I've already implemented logic in the template to auto-expand the
> >>>>> tree
> >>>>>> to
> >>>>>>>> the document for folks who have direct links. So, if you do a
> >>> Google
> >>>>>>>> Search and find the link to the MXML page, when you go to that
> page,
> >>>>>> the
> >>>>>>>> ToC will automatically look like:
> >>>>>>>>
> >>>>>>>> Welcome
> >>>>>>>> --High Level View
> >>>>>>>> --Features
> >>>>>>>> ----AS3
> >>>>>>>> ---*MXML*
> >>>>>>>> Get Started
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> If you hit the main doc page, the ToC starts out collapsed so that
> >>>>> Get
> >>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So
> the
> >>>>> ToC
> >>>>>>>> initially looks like:
> >>>>>>>>
> >>>>>>>> Welcome
> >>>>>>>> Get Started
> >>>>>>>>
> >>>>>>>> Now let's say you expand both Welcome and Get Started so you see:
> >>>>>>>>
> >>>>>>>> Welcome
> >>>>>>>> --High Level View
> >>>>>>>> --Features
> >>>>>>>> Get Started
> >>>>>>>> --Download
> >>>>>>>> --Hello World
> >>>>>>>>
> >>>>>>>> Then you click on Features. The logic that opens trees to direct
> >>>>> links
> >>>>>>> is
> >>>>>>>> going to cause the ToC to look like:
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> Welcome
> >>>>>>>> --High Level View
> >>>>>>>> --Features
> >>>>>>>> Get Started
> >>>>>>>>
> >>>>>>>> Even though you had expanded "Get Started" it will collapse when
> >>>>> going
> >>>>>> to
> >>>>>>>> the Features page. That's because, without frames, each page is
> its
> >>>>>> own
> >>>>>>>> HTML page. No state about the ToC is retained or shared.
> >>>>>>>>
> >>>>>>>> If folks are ok with that, I can probably get that to work.
> >>>>>>>>
> >>>>>>>> Thoughts?
> >>>>>>>> -Alex
> >>>>>>>>
> >>>>>>> --
> >>>>>>> Andrew Wetmore
> >>>>>>>
> >>>>>>> http://cottage14.blogspot.com/
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>>>>>> Virus-free.
> >>>>>>> www.avast.com
> >>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
> >>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
> >>>>>>>
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>> --
> >>>>>> Carlos Rovira
> >>>>>> http://about.me/carlosrovira
> >>>>>>
> >>>>>
> >>>>>
> >>>>>
> >>>>> --
> >>>>> Andrew Wetmore
> >>>>>
> >>>>> http://cottage14.blogspot.com/
> >>>>>
> >>>
> >>>
> >>
>
>
--
Andrew Wetmore
http://cottage14.blogspot.com/
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Gabe Harbs <ha...@gmail.com>.
BTW:
That site has 3 levels in the table of contents:
https://redux.js.org/docs/recipes/reducers/PrerequisiteConcepts.html <https://redux.js.org/docs/recipes/reducers/PrerequisiteConcepts.html>
> On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala <bi...@gmail.com> wrote:
>
> Here is a very good example of what the end product would look like:
> https://redux.js.org/
>
> Thanks,
> Om
>
> On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <bi...@gmail.com>
> wrote:
>
>>
>>
>> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com> wrote:
>>
>>> Is this an additional way of viewing the content or a replacement for the
>>> Jenkyll-produced site?
>>>
>>> If it’s the former, I can’t see any reason why not.
>>>
>>
>> It's an additional way. It uses the .md files from the github repo and
>> builds its own site.
>>
>> Thanks,
>> Om
>>
>>
>>>
>>> Harbs
>>>
>>>> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <bi...@gmail.com>
>>> wrote:
>>>>
>>>> I've been playing around with the tool: GitBook [www.gitbooks.io]
>>>> I was able to connect my personal fork of the royale-docs to my
>>> gitbooks.io
>>>> account. This way, all my .md files are automatically available for
>>> Docs
>>>> creation.
>>>>
>>>> Here is an example I created in a few minutes:
>>>> https://bigosmallm.gitbooks.io/royale-docs-test2/content/v/
>>> develop/Create%20An%20Application.html
>>>>
>>>> The advantages I see using this tool are:
>>>>
>>>> * Seems to be a widely used tool for documentation these days.
>>> NPMjs.org,
>>>> React, Redux, etc. use Gitbook
>>>> * Two way sync between github and gitbook app. That is, you can create
>>> an
>>>> .md file on github and see it on gitbook. You can also create more
>>> content
>>>> using the WYSIWYG editor on Gitbook, which will be synced to the github
>>>> repo.
>>>> * Seems pretty straightforward to create a TOC. It includes support for
>>>> tree structure by default
>>>> * We can choose to use the web app on gitbook.com or use the open
>>>> source(Apache V2 licensed | https://github.com/GitbookIO/gitbook)
>>> command
>>>> line tool. The CLI will help us integrate with our Jenkins build for
>>>> example.
>>>> * Allows users to provide feedback on the site itself
>>>> * Allows us to point the docs site to our custom domain address
>>>>
>>>>
>>>> If there is more interest in trying this out, I can set up an
>>> Organization
>>>> account (free) and add users as needed.
>>>>
>>>> Thanks,
>>>> Om
>>>>
>>>> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <co...@gmail.com>
>>> wrote:
>>>>
>>>>> If the ToC accordions properly and we need three levels, I do not see
>>> why
>>>>> three levels would cause more confusion than two levels. If this is a
>>>>> resource providing information people are going to need to use Royale,
>>> and
>>>>> if that information is not readily available elsewhere, then we should
>>> make
>>>>> the ToC fit the information, not the other way around.
>>>>>
>>>>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
>>> carlosrovira@apache.org>
>>>>> wrote:
>>>>>
>>>>>> Hi Alex,
>>>>>>
>>>>>> for TOC. One think that's very important to me: Please only *two
>>> levels*
>>>>> in
>>>>>> TOC. For simplicity and clarity. Like the demo page I did. It's the
>>>>>> standard right now and a three level only created confusion. Again see
>>>>>> Angular and React sites to match what they did and take it as a
>>>>> reference.
>>>>>>
>>>>>> For states. I think the trick here is that a .md page has some
>>> variables
>>>>>> that will make the right top level branch open in TOC and as well make
>>>>> the
>>>>>> right sub option appears as selected (strong type) and without link.
>>> As
>>>>> we
>>>>>> are dealing with static GitHub pages I think there's no concept of
>>>>>> component, only that all pages has the TOC added to the sidebar.
>>>>>>
>>>>>>
>>>>>>
>>>>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>>>>>>
>>>>>>> What you describe sounds fine to me. I don't think we need to worry
>>>>> about
>>>>>>> breadcrumbs and state and helping people go backwards through their
>>>>>> series
>>>>>>> of clicks.
>>>>>>>
>>>>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <aharui@adobe.com.invalid
>>>>
>>>>>>> wrote:
>>>>>>>
>>>>>>>> Breaking out a separate thread on this...
>>>>>>>>
>>>>>>>> Thinking about this some more, I think I can generate an interactive
>>>>>>>> control with Jekyll, but I don't know how to make it retain state.
>>> I
>>>>>>>> think that might require cookies and/or frames.
>>>>>>>>
>>>>>>>> For example, let's say the TOC looked like:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> ----AS3
>>>>>>>> ----MXML
>>>>>>>> Get Started
>>>>>>>> --Download
>>>>>>>> --Hello World
>>>>>>>>
>>>>>>>> I've already implemented logic in the template to auto-expand the
>>>>> tree
>>>>>> to
>>>>>>>> the document for folks who have direct links. So, if you do a
>>> Google
>>>>>>>> Search and find the link to the MXML page, when you go to that page,
>>>>>> the
>>>>>>>> ToC will automatically look like:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> ----AS3
>>>>>>>> ---*MXML*
>>>>>>>> Get Started
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> If you hit the main doc page, the ToC starts out collapsed so that
>>>>> Get
>>>>>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So the
>>>>> ToC
>>>>>>>> initially looks like:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> Get Started
>>>>>>>>
>>>>>>>> Now let's say you expand both Welcome and Get Started so you see:
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> Get Started
>>>>>>>> --Download
>>>>>>>> --Hello World
>>>>>>>>
>>>>>>>> Then you click on Features. The logic that opens trees to direct
>>>>> links
>>>>>>> is
>>>>>>>> going to cause the ToC to look like:
>>>>>>>>
>>>>>>>>
>>>>>>>> Welcome
>>>>>>>> --High Level View
>>>>>>>> --Features
>>>>>>>> Get Started
>>>>>>>>
>>>>>>>> Even though you had expanded "Get Started" it will collapse when
>>>>> going
>>>>>> to
>>>>>>>> the Features page. That's because, without frames, each page is its
>>>>>> own
>>>>>>>> HTML page. No state about the ToC is retained or shared.
>>>>>>>>
>>>>>>>> If folks are ok with that, I can probably get that to work.
>>>>>>>>
>>>>>>>> Thoughts?
>>>>>>>> -Alex
>>>>>>>>
>>>>>>> --
>>>>>>> Andrew Wetmore
>>>>>>>
>>>>>>> http://cottage14.blogspot.com/
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>>>>>> Virus-free.
>>>>>>> www.avast.com
>>>>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>>>>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>>>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Carlos Rovira
>>>>>> http://about.me/carlosrovira
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Andrew Wetmore
>>>>>
>>>>> http://cottage14.blogspot.com/
>>>>>
>>>
>>>
>>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by OmPrakash Muppirala <bi...@gmail.com>.
Here is a very good example of what the end product would look like:
https://redux.js.org/
Thanks,
Om
On Sun, Jan 28, 2018 at 3:14 AM, OmPrakash Muppirala <bi...@gmail.com>
wrote:
>
>
> On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com> wrote:
>
>> Is this an additional way of viewing the content or a replacement for the
>> Jenkyll-produced site?
>>
>> If it’s the former, I can’t see any reason why not.
>>
>
> It's an additional way. It uses the .md files from the github repo and
> builds its own site.
>
> Thanks,
> Om
>
>
>>
>> Harbs
>>
>> > On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <bi...@gmail.com>
>> wrote:
>> >
>> > I've been playing around with the tool: GitBook [www.gitbooks.io]
>> > I was able to connect my personal fork of the royale-docs to my
>> gitbooks.io
>> > account. This way, all my .md files are automatically available for
>> Docs
>> > creation.
>> >
>> > Here is an example I created in a few minutes:
>> > https://bigosmallm.gitbooks.io/royale-docs-test2/content/v/
>> develop/Create%20An%20Application.html
>> >
>> > The advantages I see using this tool are:
>> >
>> > * Seems to be a widely used tool for documentation these days.
>> NPMjs.org,
>> > React, Redux, etc. use Gitbook
>> > * Two way sync between github and gitbook app. That is, you can create
>> an
>> > .md file on github and see it on gitbook. You can also create more
>> content
>> > using the WYSIWYG editor on Gitbook, which will be synced to the github
>> > repo.
>> > * Seems pretty straightforward to create a TOC. It includes support for
>> > tree structure by default
>> > * We can choose to use the web app on gitbook.com or use the open
>> > source(Apache V2 licensed | https://github.com/GitbookIO/gitbook)
>> command
>> > line tool. The CLI will help us integrate with our Jenkins build for
>> > example.
>> > * Allows users to provide feedback on the site itself
>> > * Allows us to point the docs site to our custom domain address
>> >
>> >
>> > If there is more interest in trying this out, I can set up an
>> Organization
>> > account (free) and add users as needed.
>> >
>> > Thanks,
>> > Om
>> >
>> > On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <co...@gmail.com>
>> wrote:
>> >
>> >> If the ToC accordions properly and we need three levels, I do not see
>> why
>> >> three levels would cause more confusion than two levels. If this is a
>> >> resource providing information people are going to need to use Royale,
>> and
>> >> if that information is not readily available elsewhere, then we should
>> make
>> >> the ToC fit the information, not the other way around.
>> >>
>> >> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <
>> carlosrovira@apache.org>
>> >> wrote:
>> >>
>> >>> Hi Alex,
>> >>>
>> >>> for TOC. One think that's very important to me: Please only *two
>> levels*
>> >> in
>> >>> TOC. For simplicity and clarity. Like the demo page I did. It's the
>> >>> standard right now and a three level only created confusion. Again see
>> >>> Angular and React sites to match what they did and take it as a
>> >> reference.
>> >>>
>> >>> For states. I think the trick here is that a .md page has some
>> variables
>> >>> that will make the right top level branch open in TOC and as well make
>> >> the
>> >>> right sub option appears as selected (strong type) and without link.
>> As
>> >> we
>> >>> are dealing with static GitHub pages I think there's no concept of
>> >>> component, only that all pages has the TOC added to the sidebar.
>> >>>
>> >>>
>> >>>
>> >>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>> >>>
>> >>>> What you describe sounds fine to me. I don't think we need to worry
>> >> about
>> >>>> breadcrumbs and state and helping people go backwards through their
>> >>> series
>> >>>> of clicks.
>> >>>>
>> >>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <aharui@adobe.com.invalid
>> >
>> >>>> wrote:
>> >>>>
>> >>>>> Breaking out a separate thread on this...
>> >>>>>
>> >>>>> Thinking about this some more, I think I can generate an interactive
>> >>>>> control with Jekyll, but I don't know how to make it retain state.
>> I
>> >>>>> think that might require cookies and/or frames.
>> >>>>>
>> >>>>> For example, let's say the TOC looked like:
>> >>>>>
>> >>>>> Welcome
>> >>>>> --High Level View
>> >>>>> --Features
>> >>>>> ----AS3
>> >>>>> ----MXML
>> >>>>> Get Started
>> >>>>> --Download
>> >>>>> --Hello World
>> >>>>>
>> >>>>> I've already implemented logic in the template to auto-expand the
>> >> tree
>> >>> to
>> >>>>> the document for folks who have direct links. So, if you do a
>> Google
>> >>>>> Search and find the link to the MXML page, when you go to that page,
>> >>> the
>> >>>>> ToC will automatically look like:
>> >>>>>
>> >>>>> Welcome
>> >>>>> --High Level View
>> >>>>> --Features
>> >>>>> ----AS3
>> >>>>> ---*MXML*
>> >>>>> Get Started
>> >>>>>
>> >>>>>
>> >>>>>
>> >>>>> If you hit the main doc page, the ToC starts out collapsed so that
>> >> Get
>> >>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So the
>> >> ToC
>> >>>>> initially looks like:
>> >>>>>
>> >>>>> Welcome
>> >>>>> Get Started
>> >>>>>
>> >>>>> Now let's say you expand both Welcome and Get Started so you see:
>> >>>>>
>> >>>>> Welcome
>> >>>>> --High Level View
>> >>>>> --Features
>> >>>>> Get Started
>> >>>>> --Download
>> >>>>> --Hello World
>> >>>>>
>> >>>>> Then you click on Features. The logic that opens trees to direct
>> >> links
>> >>>> is
>> >>>>> going to cause the ToC to look like:
>> >>>>>
>> >>>>>
>> >>>>> Welcome
>> >>>>> --High Level View
>> >>>>> --Features
>> >>>>> Get Started
>> >>>>>
>> >>>>> Even though you had expanded "Get Started" it will collapse when
>> >> going
>> >>> to
>> >>>>> the Features page. That's because, without frames, each page is its
>> >>> own
>> >>>>> HTML page. No state about the ToC is retained or shared.
>> >>>>>
>> >>>>> If folks are ok with that, I can probably get that to work.
>> >>>>>
>> >>>>> Thoughts?
>> >>>>> -Alex
>> >>>>>
>> >>>> --
>> >>>> Andrew Wetmore
>> >>>>
>> >>>> http://cottage14.blogspot.com/
>> >>>>
>> >>>>
>> >>>>
>> >>>>
>> >>>>
>> >>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>> >>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>>> Virus-free.
>> >>>> www.avast.com
>> >>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>> >>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>> >>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>> >>>>
>> >>>
>> >>>
>> >>>
>> >>> --
>> >>> Carlos Rovira
>> >>> http://about.me/carlosrovira
>> >>>
>> >>
>> >>
>> >>
>> >> --
>> >> Andrew Wetmore
>> >>
>> >> http://cottage14.blogspot.com/
>> >>
>>
>>
>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by OmPrakash Muppirala <bi...@gmail.com>.
On Sun, Jan 28, 2018 at 3:13 AM, Gabe Harbs <ha...@gmail.com> wrote:
> Is this an additional way of viewing the content or a replacement for the
> Jenkyll-produced site?
>
> If it’s the former, I can’t see any reason why not.
>
It's an additional way. It uses the .md files from the github repo and
builds its own site.
Thanks,
Om
>
> Harbs
>
> > On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <bi...@gmail.com>
> wrote:
> >
> > I've been playing around with the tool: GitBook [www.gitbooks.io]
> > I was able to connect my personal fork of the royale-docs to my
> gitbooks.io
> > account. This way, all my .md files are automatically available for Docs
> > creation.
> >
> > Here is an example I created in a few minutes:
> > https://bigosmallm.gitbooks.io/royale-docs-test2/content/
> v/develop/Create%20An%20Application.html
> >
> > The advantages I see using this tool are:
> >
> > * Seems to be a widely used tool for documentation these days.
> NPMjs.org,
> > React, Redux, etc. use Gitbook
> > * Two way sync between github and gitbook app. That is, you can create
> an
> > .md file on github and see it on gitbook. You can also create more
> content
> > using the WYSIWYG editor on Gitbook, which will be synced to the github
> > repo.
> > * Seems pretty straightforward to create a TOC. It includes support for
> > tree structure by default
> > * We can choose to use the web app on gitbook.com or use the open
> > source(Apache V2 licensed | https://github.com/GitbookIO/gitbook)
> command
> > line tool. The CLI will help us integrate with our Jenkins build for
> > example.
> > * Allows users to provide feedback on the site itself
> > * Allows us to point the docs site to our custom domain address
> >
> >
> > If there is more interest in trying this out, I can set up an
> Organization
> > account (free) and add users as needed.
> >
> > Thanks,
> > Om
> >
> > On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <co...@gmail.com>
> wrote:
> >
> >> If the ToC accordions properly and we need three levels, I do not see
> why
> >> three levels would cause more confusion than two levels. If this is a
> >> resource providing information people are going to need to use Royale,
> and
> >> if that information is not readily available elsewhere, then we should
> make
> >> the ToC fit the information, not the other way around.
> >>
> >> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <carlosrovira@apache.org
> >
> >> wrote:
> >>
> >>> Hi Alex,
> >>>
> >>> for TOC. One think that's very important to me: Please only *two
> levels*
> >> in
> >>> TOC. For simplicity and clarity. Like the demo page I did. It's the
> >>> standard right now and a three level only created confusion. Again see
> >>> Angular and React sites to match what they did and take it as a
> >> reference.
> >>>
> >>> For states. I think the trick here is that a .md page has some
> variables
> >>> that will make the right top level branch open in TOC and as well make
> >> the
> >>> right sub option appears as selected (strong type) and without link. As
> >> we
> >>> are dealing with static GitHub pages I think there's no concept of
> >>> component, only that all pages has the TOC added to the sidebar.
> >>>
> >>>
> >>>
> >>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
> >>>
> >>>> What you describe sounds fine to me. I don't think we need to worry
> >> about
> >>>> breadcrumbs and state and helping people go backwards through their
> >>> series
> >>>> of clicks.
> >>>>
> >>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <aharui@adobe.com.invalid
> >
> >>>> wrote:
> >>>>
> >>>>> Breaking out a separate thread on this...
> >>>>>
> >>>>> Thinking about this some more, I think I can generate an interactive
> >>>>> control with Jekyll, but I don't know how to make it retain state. I
> >>>>> think that might require cookies and/or frames.
> >>>>>
> >>>>> For example, let's say the TOC looked like:
> >>>>>
> >>>>> Welcome
> >>>>> --High Level View
> >>>>> --Features
> >>>>> ----AS3
> >>>>> ----MXML
> >>>>> Get Started
> >>>>> --Download
> >>>>> --Hello World
> >>>>>
> >>>>> I've already implemented logic in the template to auto-expand the
> >> tree
> >>> to
> >>>>> the document for folks who have direct links. So, if you do a Google
> >>>>> Search and find the link to the MXML page, when you go to that page,
> >>> the
> >>>>> ToC will automatically look like:
> >>>>>
> >>>>> Welcome
> >>>>> --High Level View
> >>>>> --Features
> >>>>> ----AS3
> >>>>> ---*MXML*
> >>>>> Get Started
> >>>>>
> >>>>>
> >>>>>
> >>>>> If you hit the main doc page, the ToC starts out collapsed so that
> >> Get
> >>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So the
> >> ToC
> >>>>> initially looks like:
> >>>>>
> >>>>> Welcome
> >>>>> Get Started
> >>>>>
> >>>>> Now let's say you expand both Welcome and Get Started so you see:
> >>>>>
> >>>>> Welcome
> >>>>> --High Level View
> >>>>> --Features
> >>>>> Get Started
> >>>>> --Download
> >>>>> --Hello World
> >>>>>
> >>>>> Then you click on Features. The logic that opens trees to direct
> >> links
> >>>> is
> >>>>> going to cause the ToC to look like:
> >>>>>
> >>>>>
> >>>>> Welcome
> >>>>> --High Level View
> >>>>> --Features
> >>>>> Get Started
> >>>>>
> >>>>> Even though you had expanded "Get Started" it will collapse when
> >> going
> >>> to
> >>>>> the Features page. That's because, without frames, each page is its
> >>> own
> >>>>> HTML page. No state about the ToC is retained or shared.
> >>>>>
> >>>>> If folks are ok with that, I can probably get that to work.
> >>>>>
> >>>>> Thoughts?
> >>>>> -Alex
> >>>>>
> >>>> --
> >>>> Andrew Wetmore
> >>>>
> >>>> http://cottage14.blogspot.com/
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
> >>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>>> Virus-free.
> >>>> www.avast.com
> >>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
> >>>> source=link&utm_campaign=sig-email&utm_content=webmail>
> >>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
> >>>>
> >>>
> >>>
> >>>
> >>> --
> >>> Carlos Rovira
> >>> http://about.me/carlosrovira
> >>>
> >>
> >>
> >>
> >> --
> >> Andrew Wetmore
> >>
> >> http://cottage14.blogspot.com/
> >>
>
>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Gabe Harbs <ha...@gmail.com>.
Is this an additional way of viewing the content or a replacement for the Jenkyll-produced site?
If it’s the former, I can’t see any reason why not.
Harbs
> On Jan 28, 2018, at 1:09 PM, OmPrakash Muppirala <bi...@gmail.com> wrote:
>
> I've been playing around with the tool: GitBook [www.gitbooks.io]
> I was able to connect my personal fork of the royale-docs to my gitbooks.io
> account. This way, all my .md files are automatically available for Docs
> creation.
>
> Here is an example I created in a few minutes:
> https://bigosmallm.gitbooks.io/royale-docs-test2/content/v/develop/Create%20An%20Application.html
>
> The advantages I see using this tool are:
>
> * Seems to be a widely used tool for documentation these days. NPMjs.org,
> React, Redux, etc. use Gitbook
> * Two way sync between github and gitbook app. That is, you can create an
> .md file on github and see it on gitbook. You can also create more content
> using the WYSIWYG editor on Gitbook, which will be synced to the github
> repo.
> * Seems pretty straightforward to create a TOC. It includes support for
> tree structure by default
> * We can choose to use the web app on gitbook.com or use the open
> source(Apache V2 licensed | https://github.com/GitbookIO/gitbook) command
> line tool. The CLI will help us integrate with our Jenkins build for
> example.
> * Allows users to provide feedback on the site itself
> * Allows us to point the docs site to our custom domain address
>
>
> If there is more interest in trying this out, I can set up an Organization
> account (free) and add users as needed.
>
> Thanks,
> Om
>
> On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <co...@gmail.com> wrote:
>
>> If the ToC accordions properly and we need three levels, I do not see why
>> three levels would cause more confusion than two levels. If this is a
>> resource providing information people are going to need to use Royale, and
>> if that information is not readily available elsewhere, then we should make
>> the ToC fit the information, not the other way around.
>>
>> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <ca...@apache.org>
>> wrote:
>>
>>> Hi Alex,
>>>
>>> for TOC. One think that's very important to me: Please only *two levels*
>> in
>>> TOC. For simplicity and clarity. Like the demo page I did. It's the
>>> standard right now and a three level only created confusion. Again see
>>> Angular and React sites to match what they did and take it as a
>> reference.
>>>
>>> For states. I think the trick here is that a .md page has some variables
>>> that will make the right top level branch open in TOC and as well make
>> the
>>> right sub option appears as selected (strong type) and without link. As
>> we
>>> are dealing with static GitHub pages I think there's no concept of
>>> component, only that all pages has the TOC added to the sidebar.
>>>
>>>
>>>
>>> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>>>
>>>> What you describe sounds fine to me. I don't think we need to worry
>> about
>>>> breadcrumbs and state and helping people go backwards through their
>>> series
>>>> of clicks.
>>>>
>>>> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <ah...@adobe.com.invalid>
>>>> wrote:
>>>>
>>>>> Breaking out a separate thread on this...
>>>>>
>>>>> Thinking about this some more, I think I can generate an interactive
>>>>> control with Jekyll, but I don't know how to make it retain state. I
>>>>> think that might require cookies and/or frames.
>>>>>
>>>>> For example, let's say the TOC looked like:
>>>>>
>>>>> Welcome
>>>>> --High Level View
>>>>> --Features
>>>>> ----AS3
>>>>> ----MXML
>>>>> Get Started
>>>>> --Download
>>>>> --Hello World
>>>>>
>>>>> I've already implemented logic in the template to auto-expand the
>> tree
>>> to
>>>>> the document for folks who have direct links. So, if you do a Google
>>>>> Search and find the link to the MXML page, when you go to that page,
>>> the
>>>>> ToC will automatically look like:
>>>>>
>>>>> Welcome
>>>>> --High Level View
>>>>> --Features
>>>>> ----AS3
>>>>> ---*MXML*
>>>>> Get Started
>>>>>
>>>>>
>>>>>
>>>>> If you hit the main doc page, the ToC starts out collapsed so that
>> Get
>>>>> Started isn't pushed down by a bunch of Welcome sub-topics. So the
>> ToC
>>>>> initially looks like:
>>>>>
>>>>> Welcome
>>>>> Get Started
>>>>>
>>>>> Now let's say you expand both Welcome and Get Started so you see:
>>>>>
>>>>> Welcome
>>>>> --High Level View
>>>>> --Features
>>>>> Get Started
>>>>> --Download
>>>>> --Hello World
>>>>>
>>>>> Then you click on Features. The logic that opens trees to direct
>> links
>>>> is
>>>>> going to cause the ToC to look like:
>>>>>
>>>>>
>>>>> Welcome
>>>>> --High Level View
>>>>> --Features
>>>>> Get Started
>>>>>
>>>>> Even though you had expanded "Get Started" it will collapse when
>> going
>>> to
>>>>> the Features page. That's because, without frames, each page is its
>>> own
>>>>> HTML page. No state about the ToC is retained or shared.
>>>>>
>>>>> If folks are ok with that, I can probably get that to work.
>>>>>
>>>>> Thoughts?
>>>>> -Alex
>>>>>
>>>> --
>>>> Andrew Wetmore
>>>>
>>>> http://cottage14.blogspot.com/
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>>> Virus-free.
>>>> www.avast.com
>>>> <https://www.avast.com/sig-email?utm_medium=email&utm_
>>>> source=link&utm_campaign=sig-email&utm_content=webmail>
>>>> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>>>>
>>>
>>>
>>>
>>> --
>>> Carlos Rovira
>>> http://about.me/carlosrovira
>>>
>>
>>
>>
>> --
>> Andrew Wetmore
>>
>> http://cottage14.blogspot.com/
>>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by OmPrakash Muppirala <bi...@gmail.com>.
I've been playing around with the tool: GitBook [www.gitbooks.io]
I was able to connect my personal fork of the royale-docs to my gitbooks.io
account. This way, all my .md files are automatically available for Docs
creation.
Here is an example I created in a few minutes:
https://bigosmallm.gitbooks.io/royale-docs-test2/content/v/develop/Create%20An%20Application.html
The advantages I see using this tool are:
* Seems to be a widely used tool for documentation these days. NPMjs.org,
React, Redux, etc. use Gitbook
* Two way sync between github and gitbook app. That is, you can create an
.md file on github and see it on gitbook. You can also create more content
using the WYSIWYG editor on Gitbook, which will be synced to the github
repo.
* Seems pretty straightforward to create a TOC. It includes support for
tree structure by default
* We can choose to use the web app on gitbook.com or use the open
source(Apache V2 licensed | https://github.com/GitbookIO/gitbook) command
line tool. The CLI will help us integrate with our Jenkins build for
example.
* Allows users to provide feedback on the site itself
* Allows us to point the docs site to our custom domain address
If there is more interest in trying this out, I can set up an Organization
account (free) and add users as needed.
Thanks,
Om
On Sun, Jan 28, 2018 at 2:53 AM, Andrew Wetmore <co...@gmail.com> wrote:
> If the ToC accordions properly and we need three levels, I do not see why
> three levels would cause more confusion than two levels. If this is a
> resource providing information people are going to need to use Royale, and
> if that information is not readily available elsewhere, then we should make
> the ToC fit the information, not the other way around.
>
> On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <ca...@apache.org>
> wrote:
>
> > Hi Alex,
> >
> > for TOC. One think that's very important to me: Please only *two levels*
> in
> > TOC. For simplicity and clarity. Like the demo page I did. It's the
> > standard right now and a three level only created confusion. Again see
> > Angular and React sites to match what they did and take it as a
> reference.
> >
> > For states. I think the trick here is that a .md page has some variables
> > that will make the right top level branch open in TOC and as well make
> the
> > right sub option appears as selected (strong type) and without link. As
> we
> > are dealing with static GitHub pages I think there's no concept of
> > component, only that all pages has the TOC added to the sidebar.
> >
> >
> >
> > 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
> >
> > > What you describe sounds fine to me. I don't think we need to worry
> about
> > > breadcrumbs and state and helping people go backwards through their
> > series
> > > of clicks.
> > >
> > > On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <ah...@adobe.com.invalid>
> > > wrote:
> > >
> > > > Breaking out a separate thread on this...
> > > >
> > > > Thinking about this some more, I think I can generate an interactive
> > > > control with Jekyll, but I don't know how to make it retain state. I
> > > > think that might require cookies and/or frames.
> > > >
> > > > For example, let's say the TOC looked like:
> > > >
> > > > Welcome
> > > > --High Level View
> > > > --Features
> > > > ----AS3
> > > > ----MXML
> > > > Get Started
> > > > --Download
> > > > --Hello World
> > > >
> > > > I've already implemented logic in the template to auto-expand the
> tree
> > to
> > > > the document for folks who have direct links. So, if you do a Google
> > > > Search and find the link to the MXML page, when you go to that page,
> > the
> > > > ToC will automatically look like:
> > > >
> > > > Welcome
> > > > --High Level View
> > > > --Features
> > > > ----AS3
> > > > ---*MXML*
> > > > Get Started
> > > >
> > > >
> > > >
> > > > If you hit the main doc page, the ToC starts out collapsed so that
> Get
> > > > Started isn't pushed down by a bunch of Welcome sub-topics. So the
> ToC
> > > > initially looks like:
> > > >
> > > > Welcome
> > > > Get Started
> > > >
> > > > Now let's say you expand both Welcome and Get Started so you see:
> > > >
> > > > Welcome
> > > > --High Level View
> > > > --Features
> > > > Get Started
> > > > --Download
> > > > --Hello World
> > > >
> > > > Then you click on Features. The logic that opens trees to direct
> links
> > > is
> > > > going to cause the ToC to look like:
> > > >
> > > >
> > > > Welcome
> > > > --High Level View
> > > > --Features
> > > > Get Started
> > > >
> > > > Even though you had expanded "Get Started" it will collapse when
> going
> > to
> > > > the Features page. That's because, without frames, each page is its
> > own
> > > > HTML page. No state about the ToC is retained or shared.
> > > >
> > > > If folks are ok with that, I can probably get that to work.
> > > >
> > > > Thoughts?
> > > > -Alex
> > > >
> > > --
> > > Andrew Wetmore
> > >
> > > http://cottage14.blogspot.com/
> > >
> > >
> > >
> > >
> > >
> > > <https://www.avast.com/sig-email?utm_medium=email&utm_
> > > source=link&utm_campaign=sig-email&utm_content=webmail>
> > > Virus-free.
> > > www.avast.com
> > > <https://www.avast.com/sig-email?utm_medium=email&utm_
> > > source=link&utm_campaign=sig-email&utm_content=webmail>
> > > <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
> > >
> >
> >
> >
> > --
> > Carlos Rovira
> > http://about.me/carlosrovira
> >
>
>
>
> --
> Andrew Wetmore
>
> http://cottage14.blogspot.com/
>
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Andrew Wetmore <co...@gmail.com>.
If the ToC accordions properly and we need three levels, I do not see why
three levels would cause more confusion than two levels. If this is a
resource providing information people are going to need to use Royale, and
if that information is not readily available elsewhere, then we should make
the ToC fit the information, not the other way around.
On Sun, Jan 28, 2018 at 5:56 AM, Carlos Rovira <ca...@apache.org>
wrote:
> Hi Alex,
>
> for TOC. One think that's very important to me: Please only *two levels* in
> TOC. For simplicity and clarity. Like the demo page I did. It's the
> standard right now and a three level only created confusion. Again see
> Angular and React sites to match what they did and take it as a reference.
>
> For states. I think the trick here is that a .md page has some variables
> that will make the right top level branch open in TOC and as well make the
> right sub option appears as selected (strong type) and without link. As we
> are dealing with static GitHub pages I think there's no concept of
> component, only that all pages has the TOC added to the sidebar.
>
>
>
> 2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
>
> > What you describe sounds fine to me. I don't think we need to worry about
> > breadcrumbs and state and helping people go backwards through their
> series
> > of clicks.
> >
> > On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <ah...@adobe.com.invalid>
> > wrote:
> >
> > > Breaking out a separate thread on this...
> > >
> > > Thinking about this some more, I think I can generate an interactive
> > > control with Jekyll, but I don't know how to make it retain state. I
> > > think that might require cookies and/or frames.
> > >
> > > For example, let's say the TOC looked like:
> > >
> > > Welcome
> > > --High Level View
> > > --Features
> > > ----AS3
> > > ----MXML
> > > Get Started
> > > --Download
> > > --Hello World
> > >
> > > I've already implemented logic in the template to auto-expand the tree
> to
> > > the document for folks who have direct links. So, if you do a Google
> > > Search and find the link to the MXML page, when you go to that page,
> the
> > > ToC will automatically look like:
> > >
> > > Welcome
> > > --High Level View
> > > --Features
> > > ----AS3
> > > ---*MXML*
> > > Get Started
> > >
> > >
> > >
> > > If you hit the main doc page, the ToC starts out collapsed so that Get
> > > Started isn't pushed down by a bunch of Welcome sub-topics. So the ToC
> > > initially looks like:
> > >
> > > Welcome
> > > Get Started
> > >
> > > Now let's say you expand both Welcome and Get Started so you see:
> > >
> > > Welcome
> > > --High Level View
> > > --Features
> > > Get Started
> > > --Download
> > > --Hello World
> > >
> > > Then you click on Features. The logic that opens trees to direct links
> > is
> > > going to cause the ToC to look like:
> > >
> > >
> > > Welcome
> > > --High Level View
> > > --Features
> > > Get Started
> > >
> > > Even though you had expanded "Get Started" it will collapse when going
> to
> > > the Features page. That's because, without frames, each page is its
> own
> > > HTML page. No state about the ToC is retained or shared.
> > >
> > > If folks are ok with that, I can probably get that to work.
> > >
> > > Thoughts?
> > > -Alex
> > >
> > --
> > Andrew Wetmore
> >
> > http://cottage14.blogspot.com/
> >
> >
> >
> >
> >
> > <https://www.avast.com/sig-email?utm_medium=email&utm_
> > source=link&utm_campaign=sig-email&utm_content=webmail>
> > Virus-free.
> > www.avast.com
> > <https://www.avast.com/sig-email?utm_medium=email&utm_
> > source=link&utm_campaign=sig-email&utm_content=webmail>
> > <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
> >
>
>
>
> --
> Carlos Rovira
> http://about.me/carlosrovira
>
--
Andrew Wetmore
http://cottage14.blogspot.com/
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Carlos Rovira <ca...@apache.org>.
Hi Alex,
for TOC. One think that's very important to me: Please only *two levels* in
TOC. For simplicity and clarity. Like the demo page I did. It's the
standard right now and a three level only created confusion. Again see
Angular and React sites to match what they did and take it as a reference.
For states. I think the trick here is that a .md page has some variables
that will make the right top level branch open in TOC and as well make the
right sub option appears as selected (strong type) and without link. As we
are dealing with static GitHub pages I think there's no concept of
component, only that all pages has the TOC added to the sidebar.
2018-01-27 1:18 GMT+01:00 Andrew Wetmore <co...@gmail.com>:
> What you describe sounds fine to me. I don't think we need to worry about
> breadcrumbs and state and helping people go backwards through their series
> of clicks.
>
> On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <ah...@adobe.com.invalid>
> wrote:
>
> > Breaking out a separate thread on this...
> >
> > Thinking about this some more, I think I can generate an interactive
> > control with Jekyll, but I don't know how to make it retain state. I
> > think that might require cookies and/or frames.
> >
> > For example, let's say the TOC looked like:
> >
> > Welcome
> > --High Level View
> > --Features
> > ----AS3
> > ----MXML
> > Get Started
> > --Download
> > --Hello World
> >
> > I've already implemented logic in the template to auto-expand the tree to
> > the document for folks who have direct links. So, if you do a Google
> > Search and find the link to the MXML page, when you go to that page, the
> > ToC will automatically look like:
> >
> > Welcome
> > --High Level View
> > --Features
> > ----AS3
> > ---*MXML*
> > Get Started
> >
> >
> >
> > If you hit the main doc page, the ToC starts out collapsed so that Get
> > Started isn't pushed down by a bunch of Welcome sub-topics. So the ToC
> > initially looks like:
> >
> > Welcome
> > Get Started
> >
> > Now let's say you expand both Welcome and Get Started so you see:
> >
> > Welcome
> > --High Level View
> > --Features
> > Get Started
> > --Download
> > --Hello World
> >
> > Then you click on Features. The logic that opens trees to direct links
> is
> > going to cause the ToC to look like:
> >
> >
> > Welcome
> > --High Level View
> > --Features
> > Get Started
> >
> > Even though you had expanded "Get Started" it will collapse when going to
> > the Features page. That's because, without frames, each page is its own
> > HTML page. No state about the ToC is retained or shared.
> >
> > If folks are ok with that, I can probably get that to work.
> >
> > Thoughts?
> > -Alex
> >
> --
> Andrew Wetmore
>
> http://cottage14.blogspot.com/
>
>
>
>
>
> <https://www.avast.com/sig-email?utm_medium=email&utm_
> source=link&utm_campaign=sig-email&utm_content=webmail>
> Virus-free.
> www.avast.com
> <https://www.avast.com/sig-email?utm_medium=email&utm_
> source=link&utm_campaign=sig-email&utm_content=webmail>
> <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>
>
--
Carlos Rovira
http://about.me/carlosrovira
Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation
Page Layout Proposal)
Posted by Andrew Wetmore <co...@gmail.com>.
What you describe sounds fine to me. I don't think we need to worry about
breadcrumbs and state and helping people go backwards through their series
of clicks.
On Fri, Jan 26, 2018 at 8:09 PM, Alex Harui <ah...@adobe.com.invalid>
wrote:
> Breaking out a separate thread on this...
>
> Thinking about this some more, I think I can generate an interactive
> control with Jekyll, but I don't know how to make it retain state. I
> think that might require cookies and/or frames.
>
> For example, let's say the TOC looked like:
>
> Welcome
> --High Level View
> --Features
> ----AS3
> ----MXML
> Get Started
> --Download
> --Hello World
>
> I've already implemented logic in the template to auto-expand the tree to
> the document for folks who have direct links. So, if you do a Google
> Search and find the link to the MXML page, when you go to that page, the
> ToC will automatically look like:
>
> Welcome
> --High Level View
> --Features
> ----AS3
> ---*MXML*
> Get Started
>
>
>
> If you hit the main doc page, the ToC starts out collapsed so that Get
> Started isn't pushed down by a bunch of Welcome sub-topics. So the ToC
> initially looks like:
>
> Welcome
> Get Started
>
> Now let's say you expand both Welcome and Get Started so you see:
>
> Welcome
> --High Level View
> --Features
> Get Started
> --Download
> --Hello World
>
> Then you click on Features. The logic that opens trees to direct links is
> going to cause the ToC to look like:
>
>
> Welcome
> --High Level View
> --Features
> Get Started
>
> Even though you had expanded "Get Started" it will collapse when going to
> the Features page. That's because, without frames, each page is its own
> HTML page. No state about the ToC is retained or shared.
>
> If folks are ok with that, I can probably get that to work.
>
> Thoughts?
> -Alex
>
--
Andrew Wetmore
http://cottage14.blogspot.com/
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
Virus-free.
www.avast.com
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
<#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>