Hi Alex, The most important point in your answer to me is the distinction between dev and user. We should indeed make this distinction. Maybe we shouldn’t contaminate the dev list with too many user questions.
To me, once we’re at user level, it’s all about ‘Usability’ and ‘Experience’. People who ‘use’ Royale should get a great experience and feel comfortable. And that’s why some of us think we’re not at v1.0 phase yet. The experience is too scrambled and confusing at this moment. A faq is literally an aggregation of questions that get asked over and over again and therefore, I agree that the questions should be asked on SO first and that the accepted answer (or a digest of the accepted answer) is copied over the faq section of our website. @Carlos: could you agree with that? I went through the docs section on our website (which is generated automatically form the royale-docs repo?) and I don’t have a satisfying experience yet. We should make ’stories’ instead of ‘pages’. If you switch between royale.apache.org and apache.github.io, you’ll see what I mean. It’s subtle but it’s there. Once you get at the ‘Welcome to Apache Royale’ page, I’m expecting the full TOC at the right hand size which stays there all the time. I’d like to see at any moment where I am. This TOC should be the same all the way. It shouldn’t change depending on the page I am viewing at the moment. Look at the doc section at reactjs.org [1] or angular.io [2] (I think we should use VAR (Vue, Angular, React) as our benchmarks) One subject is one page (our docs are too much separated into individual pages) even if the page is very long. You just scroll down until you’ve read the whole story. At all times, the navigation section should be sticky on the left (angular) or the right (react) In the Royale docs, most ’steps’ are a separate page. So it’s mostly re-arranging content, though some pages are still empty. .md pages are fine. React docs are at GitHub too (you can even edit them!). Code examples should stand out very clearly (I like the way react does: black background) Another example of great documentation is on semantic-ui-react [3] There, they make it possible to alter the react code inline. It is immediately re-rendered in the html page! Which bring me to a side track: will it be possible to post royale snippets of code on codesandbox [4] or jsfiddle [5]? On SO, if you ask a particular question concerning code, you’ll be asked to post a working example somewhere. So what I would like to propose: - We focus on asking all user questions on SO. Everyone of us who is willing answers questions. Don’t forget to upvote answer AND the question itself! TIP: if you are on SO, go to the tag section and look for apache-royale, then hit the ‘watch tag’ button underneath so you get notified of new question regarding royale. - When a question’s is accepted, and the question itself is important enough, we digest it to the faq section on our website. - We agree on a TOC for the docs. - Make a fixed navigation aside on the website. - Doc ’stories’ are written and maintained at the GitHub repo. - Docs are re-organized into well encapsulated stories and someone writes a script to update them in apache.royale.org (?). @Carlos: to me, it sounds like linking the .md file to a docs page in WordPress? Is that possible? [1] https://reactjs.org/docs/getting-started.html [2] https://angular.io/docs [3] https://react.semantic-ui.com [4] https://codesandbox.io [5] https://jsfiddle.net And a final question: do we post this kind of threads on u...@royale.org from now on? Dany > Op 1 mei 2019, om 08:55 heeft Alex Harui <aha...@adobe.com.INVALID> het > volgende geschreven: > > Hi Dany, > > I don't have any formed opinion on the best way to collect FAQ. > > FWIW, in theory, dev@ is for questions related to the development of the > framework code that goes in the Apache Royale repos. Users@ and > StackOverflow (SO) are intended to support folks using Royale to build > applications. Some Apache projects don't even have a users@ list, they only > use SO and vice-versa. I'm assuming you want to build a FAQ for application > developers and maybe SO is a good enough way to determine FAQ since folks can > upvote questions. > > Or maybe the FAQ should be about getting started and SO will cover harder > questions. I'm not sure it matters. I'll be happy if folks are asking > questions because it means they are using Royale. So try something, let's > see how it feels and adjust as we go. > > My main point in my previous post was to encourage us to use the public repos > and wikis to lower the effort for others to contribute. > > My 2 cents, > -Alex > > On 4/30/19, 10:14 PM, "Dany Dhondt" <archeme...@mac.com.INVALID> wrote: > > Hi Alex, > > Would it be an idea to launch every new question on this list with a [FAQ] > prefix, discuss it and when the answer is accepted, post it to the Faq > section? > > Dany > >> Op 1 mei 2019, om 00:45 heeft Alex Harui <aha...@adobe.com.INVALID> het >> volgende geschreven: >> >> FWIW, I would much prefer that the FAQ be part of the royale-docs so we can >> get PRs from folks. >> >> Thoughts? >> -Alex >> >> On 4/30/19, 2:08 PM, "Carlos Rovira" <carlosrov...@apache.org >> <mailto:carlosrov...@apache.org>> wrote: >> >> Hi Dany, >> >> just created you account. I write it to your @mac.com account now to send >> you user/pass >> if you don't get nothing let me know privately >> thanks >> >> El mar., 30 abr. 2019 a las 17:19, Dany Dhondt >> (<archeme...@mac.com.invalid>) >> escribió: >> >>> No. It IS the right address. Don’t know why it marked as INVALID >>> Dany >>> >>> Verstuurd vanaf mijn iPhone >>> >>>> Op 30 apr. 2019 om 17:04 heeft Carlos Rovira <carlosrov...@apache.org> >>> het volgende geschreven: >>>> >>>> Dany, >>>> please sent me the email I must use privately, since yours in the list >>> puts >>>> "invalid" so I think is not the want you use. >>>> thanks! >>>> >>>> El mar., 30 abr. 2019 a las 17:03, Carlos Rovira (< >>> carlosrov...@apache.org>) >>>> escribió: >>>> >>>>> Hi Dany, >>>>> >>>>> I already shared the actual FAQ link [1], maybe you missed it. >>>>> You can change it whatever you want, just think that changes will need >>>>> approve of the rest. >>>>> >>>>> I'll sent you know credentials in private >>>>> >>>>> thanks! >>>>> >>>>> [1] >>>>> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Froyale.apache.org%2Ffaq%2F&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632860222&sdata=KvwsnCwqChyJtEo3hRDIKCY0NV3gTwmdNsiit74t7uo%3D&reserved=0 >>>>> >>>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Froyale.apache.org%2Ffaq%2F&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632860222&sdata=KvwsnCwqChyJtEo3hRDIKCY0NV3gTwmdNsiit74t7uo%3D&reserved=0> >>>>> >>>>> El mar., 30 abr. 2019 a las 16:54, Dany Dhondt >>> (<archeme...@mac.com.invalid <mailto:archeme...@mac.com.invalid>>) >>>>> escribió: >>>>> >>>>>> Hi Carlos, >>>>>> >>>>>> That’s ok. >>>>>> Maybe you could setup a Faq section and create the empty base page so I >>>>>> don’t mess anything up? >>>>>> >>>>>> Thx >>>>>> Dany >>>>>> >>>>>>> Op 30 apr. 2019, om 16:42 heeft Carlos Rovira < >>> carlosrov...@apache.org <mailto:carlosrov...@apache.org>> >>>>>> het volgende geschreven: >>>>>>> >>>>>>> Hi Dany, >>>>>>> >>>>>>> I can give you access to our pre production web site, so you can >>> change >>>>>>> text content. Then as you finish others can review and see if all is >>> ok >>>>>> or >>>>>>> needs any adjustment, etc... then we willl publish it to the public >>>>>> site. >>>>>>> If you are ok I can make you and user in private. Just a warning: >>> since >>>>>> we >>>>>>> use Wordpress that use to be very sensitive to global changes, you >>>>>> should >>>>>>> try just to touch "content" (add a section, add rows, add text,...), >>>>>> but if >>>>>>> you see other changes are needed please first ask about it, since some >>>>>>> times this could lead to other derivate problems. >>>>>>> >>>>>>> thanks! >>>>>>> >>>>>>> >>>>>>> >>>>>>> El mar., 30 abr. 2019 a las 16:30, Dany Dhondt >>>>>> (<archeme...@mac.com.invalid <mailto:archeme...@mac.com.invalid>>) >>>>>>> escribió: >>>>>>> >>>>>>>> Hi, >>>>>>>> >>>>>>>> Seems the idea of having a faq section on our website is supported. >>>>>>>> I’m willing to start such a faq. >>>>>>>> How do we tackle this? Do we need a database or keep it plain text? >>>>>> Anyone >>>>>>>> know of an online tool to manage it? >>>>>>>> Who’s managing the website itself? >>>>>>>> >>>>>>>> Thoughts? >>>>>>>> >>>>>>>> thx >>>>>>>> Dany >>>>>>> >>>>>>> >>>>>>> >>>>>>> -- >>>>>>> Carlos Rovira >>>>>>> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632860222&sdata=VUzyiR21Fm0kWu%2FZmgMjzSGhYOuMcznmRDGU8Ocfqpw%3D&reserved=0 >>>>>>> >>>>>>> <https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632860222&sdata=VUzyiR21Fm0kWu%2FZmgMjzSGhYOuMcznmRDGU8Ocfqpw%3D&reserved=0> >>>>>> >>>>>> >>>>> >>>>> -- >>>>> Carlos Rovira >>>>> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632860222&sdata=VUzyiR21Fm0kWu%2FZmgMjzSGhYOuMcznmRDGU8Ocfqpw%3D&reserved=0 >>>>> >>>>> <https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632870249&sdata=yrhyFzXf3TMZlbVGu%2Fw8MDcN6UVMuKuxwKc9YYxwo58%3D&reserved=0> >>>>> >>>>> >>>> >>>> -- >>>> Carlos Rovira >>>> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632870249&sdata=yrhyFzXf3TMZlbVGu%2Fw8MDcN6UVMuKuxwKc9YYxwo58%3D&reserved=0 >>>> >>>> <https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632870249&sdata=yrhyFzXf3TMZlbVGu%2Fw8MDcN6UVMuKuxwKc9YYxwo58%3D&reserved=0> >>> >>> >> >> -- >> Carlos Rovira >> >> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632870249&sdata=yrhyFzXf3TMZlbVGu%2Fw8MDcN6UVMuKuxwKc9YYxwo58%3D&reserved=0 >> >> <https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fabout.me%2Fcarlosrovira&data=02%7C01%7Caharui%40adobe.com%7Cc602a5c9a58e4c16625908d6cdf3dce5%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636922844632870249&sdata=yrhyFzXf3TMZlbVGu%2Fw8MDcN6UVMuKuxwKc9YYxwo58%3D&reserved=0> > >
