royale-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gabe Harbs <harbs.li...@gmail.com>
Subject Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation Page Layout Proposal)
Date Sun, 28 Jan 2018 11:33:09 GMT
I’d say “go for it”!

> On Jan 28, 2018, at 1:20 PM, OmPrakash Muppirala <bigosmallm@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 <harbs.lists@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 <cottage14@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 <cottage14@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/
>>>>> 
>>> 
>>> 
>> 


Mime
View raw message