You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@royale.apache.org by Dany Dhondt <ar...@mac.com.INVALID> on 2019/05/05 10:14:46 UTC
Royale docs website integration
HI,
I’d like to propose a project to re-implement the docs.
The project would consist of two parts:
1. Build a Royale webpage that consists of a ‘doc page viewer’ to the left and a sticky toc content list on the right.
The content is pulled out from our docs repo on GitHub using this basic scheme [1]
The page would then be integrated into our WP site so the user doesn’t get pulled away from the main site.
The look and feel would be identical to the main site too.
2. Re-arrange and extend the doc pages into more encapsulated ’stories’. Every story has a distinct beginning and end and covers one major part of Royale’s workflow.
I don’t know what’s the best way to do this. I don’t want to mess up what exists so should I make a new folder inside the current repo to put the stories?
All stories should off course be agreed upon before they get published.
I will do this work in cooperation with Carlos.
Carlos and me would also be working on extending TourDeJewel
Thoughts?
Dany
[1] https://drive.google.com/open?id=1BwAEnTFnGf5k-hjvp1XUSdBdO2viALd2
Re: Royale docs website integration
Posted by Carlos Rovira <ca...@apache.org>.
Hi,
I totally agree with Alex. Pages should be easy to create and edit in
Github and if we create a web view using a Royale app, this should be just
something we create a put on the web to pull the GitHub data on demand, so
people don't nee to know about that tool and they continue to work agains
GitHub since is the most easy.
A first place seems easy for what Dany exposed, I think we need to do it
progressively first loading GitHub content, then getting a sticky menu on
the right, then making that menu change content on the left. If we get at
that point with a good looking layout/css, that will be great. Then I think
we'll need to embed royale examples, that I think is done via iframe in
GitHub so we can talk about something and then show an example running.
El lun., 6 may. 2019 a las 18:43, Alex Harui (<ah...@adobe.com.invalid>)
escribió:
> I don't have an opinion on what we end up doing to the docs, but I have
> two recommendations:
>
> 1) Use a branch in royale-docs for your changes if you plan to continue
> managing content in royale-docs
> 2) Try to design a system that makes it easy and fast to offer edits to
> the docs. If the steps to make your first edit involve downloading and
> building an app, that might be a barrier to entry. If the app running on
> our website can be hotwired to pull content from someplace else so you
> don't have to build it and can see your edits before pushing the PR, that
> would be awesome. My main point is to try to avoid creating something that
> looks great but is hard to change. I would trade-off some visual
> excellence in favor of making it easier for many to help out instead of
> relying on a few experts.
>
> I think you are saying that royale-docs (which uses GitHub Pages) is too
> limiting. That there is no way to do navigation panels with auto-generated
> TOCs. If so, I think I believe that. We opted for GH Pages because it
> seemed like that's what all of the other cool GH projects were doing, but
> if the other projects are also moving away from GH pages, then we should
> too.
>
> My 2 cents,
> -Alex
>
> On 5/5/19, 9:50 AM, "Dany Dhondt" <ar...@mac.com.INVALID> wrote:
>
> In the proof of concept I made yesterday, I used the raw links to the
> .md files which works perfectly.
> When you go to any file on GitHub, there’s a ‘raw’ button which will
> show you the raw content of the file. Then just copy the link and you can
> use that one wherever you like.
> An example here [1]
> It’s just a hyperlink so I don’t think there’s any limitation here.
> The only thing we have to do is to parse the markdown content into
> html but there are plenty of js libs on npm to do that, so we wouldn’t have
> to write it ourselves.
>
> Dany
>
> [1]
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fapache%2Froyale-docs%2Fmaster%2Findex.md&data=02%7C01%7Caharui%40adobe.com%7Ce4c8bcf3ba7d495cfb3908d6d179c362%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636926718230562036&sdata=HHnTKIkpKBG2KvHTOC%2B6VbHV1ivyFsfUMfzkLXeElUk%3D&reserved=0
>
>
> > Op 5 mei 2019, om 16:49 heeft Carlos Rovira <ca...@apache.org>
> het volgende geschreven:
> >
> > Hi Danny,
> >
> > One question about the workflow: the new doc page viewer, will be a
> royale
> > app that retrieve the GitHub content on demand, in the same way as I
> did in
> > TDJ with source code? Will do this on demand? If we can do in that
> way, not
> > saving new files to repo, I think that would be great, since viewer
> will
> > pick fresh content each time. Maybe this could face some limitation
> of the
> > Github Rest API (don't know how many petitions it will allow per
> hour or
> > day)
> >
> > If we do in this way, we can reuse part of the code in TDJ and the
> main
> > problem will be to create the Sticky menu on the Right. That as well
> could
> > be based on current Navigator component. I could create that
> component as
> > part of Jewel.
> >
> > So having a main content part and the right stick menu with the
> ability to
> > load content as we select on the main content part, will be the
> "engine" we
> > need
> > Then we and others could help with the generation of "stories" to
> fill the
> > content.
> >
> > Thoughts?
> >
> >
> > El dom., 5 may. 2019 a las 12:23, Dany Dhondt
> (<ar...@mac.com.invalid>)
> > escribió:
> >
> >> HI,
> >>
> >> I’d like to propose a project to re-implement the docs.
> >>
> >> The project would consist of two parts:
> >>
> >> 1. Build a Royale webpage that consists of a ‘doc page viewer’ to
> the left
> >> and a sticky toc content list on the right.
> >> The content is pulled out from our docs repo on GitHub using this
> basic
> >> scheme [1]
> >> The page would then be integrated into our WP site so the user
> doesn’t get
> >> pulled away from the main site.
> >> The look and feel would be identical to the main site too.
> >>
> >> 2. Re-arrange and extend the doc pages into more encapsulated
> ’stories’.
> >> Every story has a distinct beginning and end and covers one major
> part of
> >> Royale’s workflow.
> >> I don’t know what’s the best way to do this. I don’t want to mess
> up what
> >> exists so should I make a new folder inside the current repo to put
> the
> >> stories?
> >> All stories should off course be agreed upon before they get
> published.
> >>
> >> I will do this work in cooperation with Carlos.
> >> Carlos and me would also be working on extending TourDeJewel
> >>
> >> Thoughts?
> >>
> >> Dany
> >>
> >>
> >>
> >>
> >> [1]
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdrive.google.com%2Fopen%3Fid%3D1BwAEnTFnGf5k-hjvp1XUSdBdO2viALd2&data=02%7C01%7Caharui%40adobe.com%7Ce4c8bcf3ba7d495cfb3908d6d179c362%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636926718230562036&sdata=UuHrjDxo%2BTUAf%2F4mhhi7ZUYxTvVgi1Ie2DzMJdtSbaA%3D&reserved=0
> >
> >
> >
> > --
> > Carlos Rovira
> >
> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Ce4c8bcf3ba7d495cfb3908d6d179c362%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636926718230562036&sdata=SXX3lbnkCKFKc2icULZOAK2HMSUcBIWmYfv5LTFOri8%3D&reserved=0
>
>
>
>
--
Carlos Rovira
http://about.me/carlosrovira
Re: Royale docs website integration
Posted by Alex Harui <ah...@adobe.com.INVALID>.
I don't have an opinion on what we end up doing to the docs, but I have two recommendations:
1) Use a branch in royale-docs for your changes if you plan to continue managing content in royale-docs
2) Try to design a system that makes it easy and fast to offer edits to the docs. If the steps to make your first edit involve downloading and building an app, that might be a barrier to entry. If the app running on our website can be hotwired to pull content from someplace else so you don't have to build it and can see your edits before pushing the PR, that would be awesome. My main point is to try to avoid creating something that looks great but is hard to change. I would trade-off some visual excellence in favor of making it easier for many to help out instead of relying on a few experts.
I think you are saying that royale-docs (which uses GitHub Pages) is too limiting. That there is no way to do navigation panels with auto-generated TOCs. If so, I think I believe that. We opted for GH Pages because it seemed like that's what all of the other cool GH projects were doing, but if the other projects are also moving away from GH pages, then we should too.
My 2 cents,
-Alex
On 5/5/19, 9:50 AM, "Dany Dhondt" <ar...@mac.com.INVALID> wrote:
In the proof of concept I made yesterday, I used the raw links to the .md files which works perfectly.
When you go to any file on GitHub, there’s a ‘raw’ button which will show you the raw content of the file. Then just copy the link and you can use that one wherever you like.
An example here [1]
It’s just a hyperlink so I don’t think there’s any limitation here.
The only thing we have to do is to parse the markdown content into html but there are plenty of js libs on npm to do that, so we wouldn’t have to write it ourselves.
Dany
[1] https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fapache%2Froyale-docs%2Fmaster%2Findex.md&data=02%7C01%7Caharui%40adobe.com%7Ce4c8bcf3ba7d495cfb3908d6d179c362%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636926718230562036&sdata=HHnTKIkpKBG2KvHTOC%2B6VbHV1ivyFsfUMfzkLXeElUk%3D&reserved=0
> Op 5 mei 2019, om 16:49 heeft Carlos Rovira <ca...@apache.org> het volgende geschreven:
>
> Hi Danny,
>
> One question about the workflow: the new doc page viewer, will be a royale
> app that retrieve the GitHub content on demand, in the same way as I did in
> TDJ with source code? Will do this on demand? If we can do in that way, not
> saving new files to repo, I think that would be great, since viewer will
> pick fresh content each time. Maybe this could face some limitation of the
> Github Rest API (don't know how many petitions it will allow per hour or
> day)
>
> If we do in this way, we can reuse part of the code in TDJ and the main
> problem will be to create the Sticky menu on the Right. That as well could
> be based on current Navigator component. I could create that component as
> part of Jewel.
>
> So having a main content part and the right stick menu with the ability to
> load content as we select on the main content part, will be the "engine" we
> need
> Then we and others could help with the generation of "stories" to fill the
> content.
>
> Thoughts?
>
>
> El dom., 5 may. 2019 a las 12:23, Dany Dhondt (<ar...@mac.com.invalid>)
> escribió:
>
>> HI,
>>
>> I’d like to propose a project to re-implement the docs.
>>
>> The project would consist of two parts:
>>
>> 1. Build a Royale webpage that consists of a ‘doc page viewer’ to the left
>> and a sticky toc content list on the right.
>> The content is pulled out from our docs repo on GitHub using this basic
>> scheme [1]
>> The page would then be integrated into our WP site so the user doesn’t get
>> pulled away from the main site.
>> The look and feel would be identical to the main site too.
>>
>> 2. Re-arrange and extend the doc pages into more encapsulated ’stories’.
>> Every story has a distinct beginning and end and covers one major part of
>> Royale’s workflow.
>> I don’t know what’s the best way to do this. I don’t want to mess up what
>> exists so should I make a new folder inside the current repo to put the
>> stories?
>> All stories should off course be agreed upon before they get published.
>>
>> I will do this work in cooperation with Carlos.
>> Carlos and me would also be working on extending TourDeJewel
>>
>> Thoughts?
>>
>> Dany
>>
>>
>>
>>
>> [1] https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdrive.google.com%2Fopen%3Fid%3D1BwAEnTFnGf5k-hjvp1XUSdBdO2viALd2&data=02%7C01%7Caharui%40adobe.com%7Ce4c8bcf3ba7d495cfb3908d6d179c362%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636926718230562036&sdata=UuHrjDxo%2BTUAf%2F4mhhi7ZUYxTvVgi1Ie2DzMJdtSbaA%3D&reserved=0
>
>
>
> --
> Carlos Rovira
> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Ce4c8bcf3ba7d495cfb3908d6d179c362%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636926718230562036&sdata=SXX3lbnkCKFKc2icULZOAK2HMSUcBIWmYfv5LTFOri8%3D&reserved=0
Re: Royale docs website integration
Posted by Dany Dhondt <ar...@mac.com.INVALID>.
In the proof of concept I made yesterday, I used the raw links to the .md files which works perfectly.
When you go to any file on GitHub, there’s a ‘raw’ button which will show you the raw content of the file. Then just copy the link and you can use that one wherever you like.
An example here [1]
It’s just a hyperlink so I don’t think there’s any limitation here.
The only thing we have to do is to parse the markdown content into html but there are plenty of js libs on npm to do that, so we wouldn’t have to write it ourselves.
Dany
[1] https://raw.githubusercontent.com/apache/royale-docs/master/index.md
> Op 5 mei 2019, om 16:49 heeft Carlos Rovira <ca...@apache.org> het volgende geschreven:
>
> Hi Danny,
>
> One question about the workflow: the new doc page viewer, will be a royale
> app that retrieve the GitHub content on demand, in the same way as I did in
> TDJ with source code? Will do this on demand? If we can do in that way, not
> saving new files to repo, I think that would be great, since viewer will
> pick fresh content each time. Maybe this could face some limitation of the
> Github Rest API (don't know how many petitions it will allow per hour or
> day)
>
> If we do in this way, we can reuse part of the code in TDJ and the main
> problem will be to create the Sticky menu on the Right. That as well could
> be based on current Navigator component. I could create that component as
> part of Jewel.
>
> So having a main content part and the right stick menu with the ability to
> load content as we select on the main content part, will be the "engine" we
> need
> Then we and others could help with the generation of "stories" to fill the
> content.
>
> Thoughts?
>
>
> El dom., 5 may. 2019 a las 12:23, Dany Dhondt (<ar...@mac.com.invalid>)
> escribió:
>
>> HI,
>>
>> I’d like to propose a project to re-implement the docs.
>>
>> The project would consist of two parts:
>>
>> 1. Build a Royale webpage that consists of a ‘doc page viewer’ to the left
>> and a sticky toc content list on the right.
>> The content is pulled out from our docs repo on GitHub using this basic
>> scheme [1]
>> The page would then be integrated into our WP site so the user doesn’t get
>> pulled away from the main site.
>> The look and feel would be identical to the main site too.
>>
>> 2. Re-arrange and extend the doc pages into more encapsulated ’stories’.
>> Every story has a distinct beginning and end and covers one major part of
>> Royale’s workflow.
>> I don’t know what’s the best way to do this. I don’t want to mess up what
>> exists so should I make a new folder inside the current repo to put the
>> stories?
>> All stories should off course be agreed upon before they get published.
>>
>> I will do this work in cooperation with Carlos.
>> Carlos and me would also be working on extending TourDeJewel
>>
>> Thoughts?
>>
>> Dany
>>
>>
>>
>>
>> [1] https://drive.google.com/open?id=1BwAEnTFnGf5k-hjvp1XUSdBdO2viALd2
>
>
>
> --
> Carlos Rovira
> http://about.me/carlosrovira
Re: Royale docs website integration
Posted by Carlos Rovira <ca...@apache.org>.
Hi Danny,
One question about the workflow: the new doc page viewer, will be a royale
app that retrieve the GitHub content on demand, in the same way as I did in
TDJ with source code? Will do this on demand? If we can do in that way, not
saving new files to repo, I think that would be great, since viewer will
pick fresh content each time. Maybe this could face some limitation of the
Github Rest API (don't know how many petitions it will allow per hour or
day)
If we do in this way, we can reuse part of the code in TDJ and the main
problem will be to create the Sticky menu on the Right. That as well could
be based on current Navigator component. I could create that component as
part of Jewel.
So having a main content part and the right stick menu with the ability to
load content as we select on the main content part, will be the "engine" we
need
Then we and others could help with the generation of "stories" to fill the
content.
Thoughts?
El dom., 5 may. 2019 a las 12:23, Dany Dhondt (<ar...@mac.com.invalid>)
escribió:
> HI,
>
> I’d like to propose a project to re-implement the docs.
>
> The project would consist of two parts:
>
> 1. Build a Royale webpage that consists of a ‘doc page viewer’ to the left
> and a sticky toc content list on the right.
> The content is pulled out from our docs repo on GitHub using this basic
> scheme [1]
> The page would then be integrated into our WP site so the user doesn’t get
> pulled away from the main site.
> The look and feel would be identical to the main site too.
>
> 2. Re-arrange and extend the doc pages into more encapsulated ’stories’.
> Every story has a distinct beginning and end and covers one major part of
> Royale’s workflow.
> I don’t know what’s the best way to do this. I don’t want to mess up what
> exists so should I make a new folder inside the current repo to put the
> stories?
> All stories should off course be agreed upon before they get published.
>
> I will do this work in cooperation with Carlos.
> Carlos and me would also be working on extending TourDeJewel
>
> Thoughts?
>
> Dany
>
>
>
>
> [1] https://drive.google.com/open?id=1BwAEnTFnGf5k-hjvp1XUSdBdO2viALd2
--
Carlos Rovira
http://about.me/carlosrovira