Oh and another thing, I would prefer we use Asciidoc than Markdown, if possible. Markdown has way to many variants and ways of doing things. Plus Asciidoc is already used for Karaf documentation.
cheers, Serge... On Wed, Aug 22, 2018 at 9:20 PM Serge Huber <[email protected]> wrote: > > Forgot to answer for the Maven stuff. Not sure what to do about this. > Maybe we don't even need it ? What does Karaf do here ? > > cheers, > Serge... > On Wed, Aug 22, 2018 at 9:19 PM Serge Huber <[email protected]> wrote: > > > > Hi François, > > > > Thanks for your work. I tried to compile the project but I got the > > following error : > > > > [INFO] Scanning for projects... > > [ERROR] [ERROR] Some problems were encountered while processing the POMs: > > [FATAL] 'version' is missing. @ line 23, column 106 > > @ > > [ERROR] The build could not read 1 project -> [Help 1] > > [ERROR] > > [ERROR] The project org.apache.unomi:site:[unknown-version] > > (/Users/loom/temp/incubator-unomi-website/pom.xml) has 1 error > > [ERROR] 'version' is missing. @ line 23, column 106 > > [ERROR] > > [ERROR] To see the full stack trace of the errors, re-run Maven with > > the -e switch. > > [ERROR] Re-run Maven using the -X switch to enable full debug logging. > > [ERROR] > > [ERROR] For more information about the errors and possible solutions, > > please read the following articles: > > [ERROR] [Help 1] > > http://cwiki.apache.org/confluence/display/MAVEN/ProjectBuildingException > > > > After adding a version however it worked fine ! > > > > I like the overall result although it seems like it is using a lot of > > space and some fonts seem really large. Also it seems some stuff is > > missing like the getting started (I couldn't find it). > > > > I like the new documentation part, some nice ideas there. > > > > My biggest concern is on-boarding newcomers with the site, and I think > > they shouldn't have to read through a lot of content to understand > > what the project does. Ideally maybe we should look into producing > > some kind of video or a quick animation. > > > > Finally I tried the site on a mobile device and it seems the > > navigation completely disappears. > > > > Anyway thanks for the effort I like it ! > > > > cheers, > > Serge... > > On Wed, Aug 22, 2018 at 12:12 PM Francois Papon > > <[email protected]> wrote: > > > > > > Hi, > > > > > > I worked on a preview version of the website and published it on my > > > github repo : > > > > > > https://github.com/fpapon/incubator-unomi-website > > > > > > I also started to work on a easy way to publish the documentation from > > > markdown to HTML and PDF. > > > > > > May be it could be nice to archive the documentation related to the > > > maven project with git tag because today it's on differents folder in > > > the src/ of the project. > > > > > > Thoughts ? > > > > > > regards, > > > > > > François Papon > > > [email protected] > > > > > > Le 03/08/2018 à 00:14, Serge Huber a écrit : > > > > Thanks François, looking forward to the PR ! > > > > > > > > If you want to work on the website you're more than welcome to start > > > > working on it, as I said the more people get involved the better for > > > > the project ! > > > > > > > > Regards, > > > > Serge.. > > > > On Wed, Aug 1, 2018 at 8:48 PM Francois Papon > > > > <[email protected]> wrote: > > > >> Ok for Swagger, I will post a PR. > > > >> > > > >> About the website, let me know when you want me to start working on it > > > >> (I already have a repo on my github account). > > > >> > > > >> regards, > > > >> > > > >> François Papon > > > >> [email protected] > > > >> > > > >> Le 01/08/2018 à 18:25, Serge Huber a écrit : > > > >>> Feel free to help out on Swagger, I have little to no experience with > > > >>> it. > > > >>> > > > >>> As for the GraphQL side, it's very experimental code that is > > > >>> constantly changing right now, so be warned that things might change > > > >>> quite significantly at any point but feel free to look at it and give > > > >>> feedback or even contribute! > > > >>> > > > >>> cheers, > > > >>> Serge... > > > >>> > > > >>> Serge Huber > > > >>> CTO & Co-Founder > > > >>> > > > >>> T +41 22 361 3424 > > > >>> 9 route des Jeunes | 1227 Acacias | Switzerland > > > >>> jahia.com > > > >>> SKYPE | LINKEDIN | TWITTER | VCARD > > > >>> > > > >>> > > > >>>> JOIN OUR COMMUNITY to evaluate, get trained and to discover why > > > >>>> Jahia is a leading User Experience Platform (UXP) for Digital > > > >>>> Transformation. > > > >>> On Wed, Aug 1, 2018 at 9:00 AM Francois Papon > > > >>> <[email protected]> wrote: > > > >>>> Cool, > > > >>>> > > > >>>> If needed, I can help on the Swagger and the GraphQL integration ;) > > > >>>> > > > >>>> regards, > > > >>>> > > > >>>> François Papon > > > >>>> [email protected] > > > >>>> Yupiik - https://www.yupiik.com > > > >>>> > > > >>>> Le 31/07/2018 à 23:01, Serge Huber a écrit : > > > >>>>> Hello François, > > > >>>>> > > > >>>>> Thanks for clarifying that I wasn't aware that you could use Swagger > > > >>>>> that way. That makes sense. > > > >>>>> > > > >>>>> For GraphQL yes the final version of the CXS specification I'm also > > > >>>>> co-developing has switched from REST to GraphQL, and I'm currently > > > >>>>> implementing that in a branch to validate the design of the GraphQL > > > >>>>> schema. It's a challenge because we are doing some advanced stuff > > > >>>>> with > > > >>>>> GraphQL but the API is already a lot more powerful than the REST > > > >>>>> API. > > > >>>>> > > > >>>>> cheers, > > > >>>>> Serge... > > > >>>>> On Tue, Jul 31, 2018 at 6:25 PM Francois Papon > > > >>>>> <[email protected]> wrote: > > > >>>>>> Hi Serge, > > > >>>>>> > > > >>>>>> Thanks for your feedback :) > > > >>>>>> > > > >>>>>> I see the Miredot documentation and for me it's good. > > > >>>>>> > > > >>>>>> I propose to add Swagger (not to replace Miredot) to have a GUI to > > > >>>>>> simulate request and response for developers. > > > >>>>>> > > > >>>>>> I already used the cxf-swagger-feature in a Karaf project and the > > > >>>>>> only > > > >>>>>> bug I found it's the refresh of the json when updating the bundle > > > >>>>>> in a > > > >>>>>> started instance. > > > >>>>>> > > > >>>>>> I have in mind to propose a page on the website dedicated to the > > > >>>>>> API > > > >>>>>> like this : > > > >>>>>> > > > >>>>>> https://projects.tmforum.org/wiki/display/API/Open+API+Table > > > >>>>>> > > > >>>>>> I saw a JIRA about GraphQL integration, it's great :) > > > >>>>>> > > > >>>>>> regards, > > > >>>>>> > > > >>>>>> François Papon > > > >>>>>> [email protected] > > > >>>>>> > > > >>>>>> Le 31/07/2018 à 19:48, Serge Huber a écrit : > > > >>>>>>> Hello François, > > > >>>>>>> > > > >>>>>>> Thank you for your proposal, I really like the new design ! > > > >>>>>>> > > > >>>>>>> For me, the user documentation could be reformated to make it > > > >>>>>>> easier > > > >>>>>>> to browse and of course, it always needs improving and detailing. > > > >>>>>>> > > > >>>>>>> Concerning the REST API documentation, currently, we use another > > > >>>>>>> tool > > > >>>>>>> to generate it from the source code, and it is capable of > > > >>>>>>> documenting > > > >>>>>>> the JSON structure at the same time. The whole source code was > > > >>>>>>> documented to work with this plugin (http://www.miredot.com/) for > > > >>>>>>> which we got a free license since it is an Apache project. Are you > > > >>>>>>> suggesting we replace this with Swagger (we evaluated it at the > > > >>>>>>> time > > > >>>>>>> but it was missing some features for generating from the code) ? > > > >>>>>>> > > > >>>>>>> Regards, > > > >>>>>>> Serge... > > > >>>>>>> On Tue, Jul 31, 2018 at 2:42 PM Francois Papon > > > >>>>>>> <[email protected]> wrote: > > > >>>>>>>> Hi, > > > >>>>>>>> > > > >>>>>>>> I'm new with the Apache Unomi project and I would like to make > > > >>>>>>>> some > > > >>>>>>>> proposals around the website and the documentation :) > > > >>>>>>>> > > > >>>>>>>> *1 - Website :* > > > >>>>>>>> > > > >>>>>>>> Actually, the website is auto generate and link to the project > > > >>>>>>>> release > > > >>>>>>>> livecycle, however we could made some changes any time, like > > > >>>>>>>> posting > > > >>>>>>>> news, uses cases... > > > >>>>>>>> > > > >>>>>>>> That's why I think the website can have he's dedicated > > > >>>>>>>> repository and > > > >>>>>>>> could be only build on html static pages. > > > >>>>>>>> > > > >>>>>>>> I started a WIP with the home page and you can have a preview > > > >>>>>>>> here : > > > >>>>>>>> https://openobject.fr/unomi > > > >>>>>>>> > > > >>>>>>>> *2 - User guide :* > > > >>>>>>>> > > > >>>>>>>> The user guide is good and could be link to the release, may be > > > >>>>>>>> to major > > > >>>>>>>> release ? > > > >>>>>>>> > > > >>>>>>>> We have the documentation in md format for Github and html for > > > >>>>>>>> the > > > >>>>>>>> website, we also could have a pdf from the html. > > > >>>>>>>> > > > >>>>>>>> *3 - API Rest documentation :* > > > >>>>>>>> > > > >>>>>>>> May be we could provided an instance of Swagger from the website > > > >>>>>>>> for > > > >>>>>>>> developers, it's convenient for have some request/response > > > >>>>>>>> (their is an > > > >>>>>>>> existing cxf-swagger feature for generating the json). > > > >>>>>>>> > > > >>>>>>>> > > > >>>>>>>> If you are interesting, I can help on this items :) > > > >>>>>>>> > > > >>>>>>>> regards, > > > >>>>>>>> > > > >>>>>>>> -- > > > >>>>>>>> François Papon > > > >>>>>>>> [email protected] > > > >>>>>>>> > > > > > >
