royale-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From OmPrakash Muppirala <bigosma...@gmail.com>
Subject Re: Royale Doc Table-of-Contents UX (was Re: Royale Documentation Page Layout Proposal)
Date Sun, 28 Jan 2018 11:20:59 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message