El mié., 1 may. 2019 a las 13:18, Dany Dhondt (<[email protected]>) escribió:
> > 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? > > yeah, as I'm reading this discussion I feel that's the right way. We started the current FAQ in website to have something. for people coming to the tech. As we have real people using it, that has more sense. So maybe we can in the end remove the current FAQ page on the site, or translate the questions to SOF, or even left the page with the questions in website, but link the response to SOF... for me I'm ok with do whatever folks thinks is the best way. > 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’. > ok too > > 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) > I remember when discussing this many months ago that I as well bring those experiences to the plate. For me are what we need to follow. The problem I think was technical and time and for that reason I think we end with the current solution that was far better that what we have before (nothing), but I think we should improve too. > > 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? > I think it could be possible, we should find some plugin or something in WP that could do that. It's a matter to find a way. > > [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 [email protected] > from now on? > > Don't think so, this is more a "dev" question, and users list use to be a way for users to ask devs, not the opposite. Or devs inform users... Thanks Dany! > Dany > > -- Carlos Rovira http://about.me/carlosrovira
