Comments about Quarkus documentation

[Yans]

Hello,

Not sure if anyone noticed, but there are a few comments on Quarkus documentation on HN, /r/java etc, Following are a few instances I've noticed recently.

ANYWAY... if RedHat wants to build traction for Quarkus, I'm not sure that a GraalVM fork is the silver bullet. What Quarkus really needs is a technical writer. To produce some documentation for developers who do not have 10-20 years of Java EE baggage under their belts.

https://old.reddit.com/r/java/comments/hjte61/redhat_mandrel_makes_java_native/fwqbjlj/ 

3. If you have experience with neither Spring nor Java EE, then the Micronaut documentation will probably be easier to follow. The Quarkus documentation assumes that you already know a lot about CDI and other Java EE standards, and it mostly focuses on how Quarkus differs from those specs. Their documentation SUCKS at presenting the framework to a fresh audience without all that baggage. 

https://news.ycombinator.com/item?id=23655768

Not much to be honest, but if I have to pick, it would be the documentation. Although the contents are there (and its of high quality, lot of examples), its not structured in a way that's beginner friendly. 

https://old.reddit.com/r/java/comments/gzzole/micronaut_vs_quarkus_which_is_better/ftok71r/

I rather prefer Micronaut over Quarkus. Micronaut has better documentation

https://old.reddit.com/r/java/comments/gzzole/micronaut_vs_quarkus_which_is_better/ftjb0ts/

I too kind of agree that Quarkus documentation could use some work, esp to structure in a way to make it more beginner/navigation friendly.

Thanks

Yans

[Emmanuel Bernard]

I'd love to see concrete proposals out of this. To be fair we also had the exact opposite remarks ("your doc is awesome" -- santa claus) so it's hard for us to improve without concrete issues or even proposals on how to address things differently.

One thing we have wanted to do for a long time is introduction / high level topics. I imagine high level subjects should be:

- Web

- Data

- Messaging

- Deploying

- Testing

- Security

I think that's why people feel it's easier on the Mn side, they do have such areas covered in their "reference guide" before they go into more detailed topics like we do.

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/b2f44ca7-c95c-46da-a3b8-9807e3cab25fo%40googlegroups.com.

[Loïc MATHIEU]

I agree our documentation lacks :

- Top level / introduction documentation => this is because it's just a list of guides for the moment, and not a comprehensive reference documentation.

- Technology introduction : CDI for example is not very well known as most of the time people are used to Spring annotations. Even Micronaut uses them. The current CDI guide links to the spec (argh!) then talks directly about bean discovery (I didn't have a clue about what it is the first time I read the guide). We discussed more than once the fact that Quarkus cannot copy the documentation from all the technology it integrates inside it's stack, but I still think that some of them, and CDI must be of that nature, needs to be introduced inside our guides.

Now, there will always be people finding framework 1 is better than 2, documentation 1 is better than 2, ...

There are good technical writers inside the Quarkus team (not me ;)), so I'm sure it is a matter of time and priority for our documentation to improve ;)

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CANYWk7Owpw-53sED%3D1_4mj-%2BC3vfGuQvi_zcha2rG2tR8aJ4bg%40mail.gmail.com.

[Sérgio Sousa]

I think that, on a beginner level, the structure and examples have a good quality. As a user, what I miss the most is an integration documentation with some modules (it's not always straightforward to integrate several extensions in a bundled project) as this would be the ultimate goal of a end user developer.

Maybe creating some guides for 3 - 4 uses cases integrating several modules would improve the perceived quality of the documentation.

That being said, I'm an early adopter and appreciate very much of everyone's involved!

Best regards,

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAJLxjVHFZG%2B2009iV5kmyT3snLj3HkOVMQgrkyZw_CGGdbpfrQ%40mail.gmail.com.

[Loïc MATHIEU]

@Sérgio, I like what you propose, this could of the form of blog posts and example repos that shows how to integrate multiple extensions altogether to provide most implemented use cases. Then link them from all the according extension guides.

I created some for "cloud ready" apps with hibernate with panache, openapi, metrics, ...  But it's in french in the form of a DOJO.

By the way, having them as a DOJO could also be a good idea, some "Quarkus Katas" repo with explanation of how to build the most typical use cases ...

[Emanuel Alves]

@Sérgio great idea!
@Loïc sounds great too :)

To unsubscribe from this group and stop receiving emails from it, send an email to quark...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/b2f44ca7-c95c-46da-a3b8-9807e3cab25fo%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.

To unsubscribe from this group and stop receiving emails from it, send an email to quark...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CANYWk7Owpw-53sED%3D1_4mj-%2BC3vfGuQvi_zcha2rG2tR8aJ4bg%40mail.gmail.com.

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.

To unsubscribe from this group and stop receiving emails from it, send an email to quark...@googlegroups.com.

[Aleatório .]

Hello,

How about a Getting Started Guide? I was already thinking about creating some blog posts in Portuguese to help new devs. Maybe some official documentation with baby steps would be great. 

The roadmap that I want to use to my posts is something like this:

• Create first REST API 
• With pictures from http://code.quarkus.io
• Add unit tests to REST API
• Publishing REST API with docker
• Add connection with a database to REST API
• Add integration tests (Does quarkus already have support to it?)
• Create another project to create REST client
• Add examples of configurations
• A little note of quarkus profiles
• Example with override configurations
• Logging information with different levels and different formats
• Add some HTTP interceptor to the REST server (maybe something with log, audit or security)
• Add scheduling to REST client project to connect to the REST server 

To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/ee96735a-5ea7-4708-a4cc-531af4d2cd0ao%40googlegroups.com.

--

Att.

João Lucas Scharf, o Aleatório

[Emmanuel Bernard]

Aleatorio, this looks like a good plan to me.

I always loved this doc from play framework 1

https://www.playframework.com/documentation/1.5.x/guide1 to https://www.playframework.com/documentation/1.5.x/guide12

Can you open an issue with your plan and reference. Anyone with different preferences, we can refine the plan. Of course if you have time to start working on this, that would be awesome!

Loic, indeed, CDI is too abrupt in its introduction. Can you open an issue so we offer an 2 page intro to CDI in our guide instead of pointing to the spec too abruptly?

The "reference documentation" one is one that people have asked (with different definitions) but noone has accepted to pick up so far. And I don't think the goal of a reference doc is to make life easier for newcomers.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAHzqWS7LSJ37K-vjJ3SLnhYqS1hfF4c%2BG-D%2B0qr9X-9EUzCsaA%40mail.gmail.com.

[Stuart Douglas]

I think ideally we would have a more complete introductory guide for CDI, JAX-RS and JPA, just so we cover the basics in our documentation. I don't think we want to re-document everything, but we should be able to document all the basic 'day to day' features that devs would use.

Maybe we could figure out the features we think meet this definition, then come up with a sample app that uses them all, and write a bigger guide around it to walk users through them?

Stuart

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CANYWk7Owpw-53sED%3D1_4mj-%2BC3vfGuQvi_zcha2rG2tR8aJ4bg%40mail.gmail.com.

[Martin Kouba]

Dne 06. 07. 20 v 15:56 Emmanuel Bernard napsal(a):

> Aleatorio, this looks like a good plan to me.
> I always loved this doc from play framework 1
> https://www.playframework.com/documentation/1.5.x/guide1 to
> https://www.playframework.com/documentation/1.5.x/guide12
> Can you open an issue with your plan and reference. Anyone with
> different preferences, we can refine the plan. Of course if you have
> time to start working on this, that would be awesome!
>
> Loic, indeed, CDI is too abrupt in its introduction. Can you open an
> issue so we offer an 2 page intro to CDI in our guide instead of
> pointing to the spec too abruptly?

I will try to prepare a "CDI getting started guide" this week. The
current guide is in fact named "cdi-reference" and describes mainly the
differences between the spec and Quarkus DI (limitations, non-standard
features, etc.).

>
> The "reference documentation" one is one that people have asked (with
> different definitions) but noone has accepted to pick up so far. And I
> don't think the goal of a reference doc is to make life easier for
> newcomers.
>
> On Fri, Jul 3, 2020 at 8:03 PM Aleatório . <lucas....@gmail.com
> <mailto:lucas....@gmail.com>> wrote:
>
> Hello,
>
>
> How about a Getting Started Guide? I was already thinking about
> creating some blog posts in Portuguese to help new devs. Maybe some
> official documentation with baby steps would be great.
>
> The roadmap that I want to use to my posts is something like this:
>
>

> * Create first REST API
> o With pictures from http://code.quarkus.io
> * Add unit tests to REST API
> * Publishing REST API with docker
> * Add connection with a database to REST API
> o Add integration tests (Does quarkus already have support to it?)
> * Create another project to create REST client
> * Add examples of configurations
> o A little note of quarkus profiles
> o Example with override configurations
> * Logging information with different levels and different formats
> * Add some HTTP interceptor to the REST server (maybe something

> with log, audit or security)

> * Add scheduling to REST client project to connect to the REST server

>
>
> On Fri, Jul 3, 2020 at 2:09 PM Emanuel Alves

> <emanuel....@gmail.com <mailto:emanuel....@gmail.com>>

> /ANYWAY... if RedHat wants to build traction

> for Quarkus, I'm not sure that a GraalVM
> fork is the silver bullet. What Quarkus
> really needs is a technical writer. To
> produce some documentation for developers
> who do not have 10-20 years of Java EE

> baggage under their belts./
> https://old.reddit.com/r/java/comments/hjte61/redhat_mandrel_makes_java_native/fwqbjlj/
> <https://old.reddit.com/r/java/comments/hjte61/redhat_mandrel_makes_java_native/fwqbjlj/>
>
>
> /3. If you have experience with neither

> Spring nor Java EE, then the Micronaut
> documentation will probably be easier to
> follow. The Quarkus documentation assumes
> that you already know a lot about CDI and
> other Java EE standards, and it mostly
> focuses on how Quarkus differs from those
> specs. Their documentation SUCKS at
> presenting the framework to a fresh audience

> without all that baggage. /
> https://news.ycombinator.com/item?id=23655768
>
>
> /Not much to be honest, but if I have to

> pick, it would be the documentation.
> Although the contents are there (and its of
> high quality, lot of examples), its not

> structured in a way that's beginner friendly. /
> https://old.reddit.com/r/java/comments/gzzole/micronaut_vs_quarkus_which_is_better/ftok71r/
>
>
> /I rather prefer Micronaut over Quarkus.
> Micronaut has better documentation/

> https://old.reddit.com/r/java/comments/gzzole/micronaut_vs_quarkus_which_is_better/ftjb0ts/
>
> I too kind of agree that Quarkus
> documentation could use some work, esp to
> structure in a way to make it more
> beginner/navigation friendly.
>
> Thanks
> Yans
>
> --
> You received this message because you are
> subscribed to the Google Groups "Quarkus
> Development mailing list" group.
> To unsubscribe from this group and stop
> receiving emails from it, send an email to
> quark...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/quarkus-dev/b2f44ca7-c95c-46da-a3b8-9807e3cab25fo%40googlegroups.com

> <https://groups.google.com/d/msgid/quarkus-dev/b2f44ca7-c95c-46da-a3b8-9807e3cab25fo%40googlegroups.com?utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are
> subscribed to the Google Groups "Quarkus
> Development mailing list" group.
> To unsubscribe from this group and stop
> receiving emails from it, send an email to
> quark...@googlegroups.com.
> To view this discussion on the web visit

> https://groups.google.com/d/msgid/quarkus-dev/CANYWk7Owpw-53sED%3D1_4mj-%2BC3vfGuQvi_zcha2rG2tR8aJ4bg%40mail.gmail.com
> <https://groups.google.com/d/msgid/quarkus-dev/CANYWk7Owpw-53sED%3D1_4mj-%2BC3vfGuQvi_zcha2rG2tR8aJ4bg%40mail.gmail.com?utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed
> to the Google Groups "Quarkus Development mailing
> list" group.
> To unsubscribe from this group and stop receiving
> emails from it, send an email to
> quark...@googlegroups.com.
> To view this discussion on the web visit

> https://groups.google.com/d/msgid/quarkus-dev/CAJLxjVHFZG%2B2009iV5kmyT3snLj3HkOVMQgrkyZw_CGGdbpfrQ%40mail.gmail.com
> <https://groups.google.com/d/msgid/quarkus-dev/CAJLxjVHFZG%2B2009iV5kmyT3snLj3HkOVMQgrkyZw_CGGdbpfrQ%40mail.gmail.com?utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed to the
> Google Groups "Quarkus Development mailing list" group.
> To unsubscribe from this group and stop receiving emails from

> it, send an email to quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/quarkus-dev/ee96735a-5ea7-4708-a4cc-531af4d2cd0ao%40googlegroups.com
> <https://groups.google.com/d/msgid/quarkus-dev/ee96735a-5ea7-4708-a4cc-531af4d2cd0ao%40googlegroups.com?utm_medium=email&utm_source=footer>.

>
>
>
> --
> Att.
>
> João Lucas Scharf, o Aleatório
>
> --
> You received this message because you are subscribed to the Google
> Groups "Quarkus Development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to quarkus-dev...@googlegroups.com

> <mailto:quarkus-dev...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/quarkus-dev/CAHzqWS7LSJ37K-vjJ3SLnhYqS1hfF4c%2BG-D%2B0qr9X-9EUzCsaA%40mail.gmail.com
> <https://groups.google.com/d/msgid/quarkus-dev/CAHzqWS7LSJ37K-vjJ3SLnhYqS1hfF4c%2BG-D%2B0qr9X-9EUzCsaA%40mail.gmail.com?utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "Quarkus Development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/quarkus-dev/CANYWk7P%2BV8nkT%3DWJumspmcqEd2hKOE4JB4BpKzt2ySU-u43Fdw%40mail.gmail.com
> <https://groups.google.com/d/msgid/quarkus-dev/CANYWk7P%2BV8nkT%3DWJumspmcqEd2hKOE4JB4BpKzt2ySU-u43Fdw%40mail.gmail.com?utm_medium=email&utm_source=footer>.

--
Martin Kouba
Senior Software Engineer
Red Hat, Czech Republic

[Loïc MATHIEU]

@Stuart Douglas I agree with your list of features, we should add a "getting started" section, ideally not a different guide because there are already a lot of entries inside the documentation and people may find it difficult which one to select.

There are other areas where we can at least add a "technology introduction sentence", for example the validation guide (https://quarkus.io/guides/validation) starts with "Use @Inject to inject a Validator". Introducing in a simple sentence what is bean validation is easy and will add some context for people not knowing it "Bean validation is a feature that allows to easily validate a Java Bean via a set of annotations and a Validator." + link to the list of annotations ...

I created an issue for the CDI reference guide: https://github.com/quarkusio/quarkus/issues/10510 I'm not fan of a new guide because there is already a lot of guides and people may find it difficult to know if they need to read the "getting started with CDI" or the "CDI reference" guide.

 @Martin Kouba don't hesitate to ping me to review the guide if you have time to work on it, but the best would be to have someone that didn't know CDI that review the guide.

To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/9748daf1-bb89-00fb-7ef8-966feb4338e8%40redhat.com.

[Guillaume Smet]

JPA is a bit less pressing as Spring uses it too.

I think CDI and JAX-RS (we have a lot of questions on JAX-RS) should be our priorities.

[Georgios Andrianakis]

On Tue, Jul 7, 2020 at 10:46 AM Guillaume Smet <guillau...@gmail.com> wrote:

JPA is a bit less pressing as Spring uses it too.

I think CDI and JAX-RS (we have a lot of questions on JAX-RS) should be our priorities.

+1

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CALt0%2Bo-P5QqNnVF57EbW-vDLM7S4%2BBo7LXcBFQDShwJ5vFN58A%40mail.gmail.com.

[Sérgio Sousa]

+1

Also something that could be useful would be a global topic about security, maybe highlighting the diferences and potencial use cases of the modules available. I've seen myself comparing oidc vs jwt a while ago. 

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CALeTM-%3DMtnK25xY_a2-9iko2V8CtNG4dB7dwk1Ah7iVO-uePoQ%40mail.gmail.com.

[Emmanuel Bernard]

I would repurpose the reference guide to be the getting started guide with a reference section. We don’t need more entries per technology. 

Maybe the time will come to need guides that are there but not in the menu. So only accessible from an intro fanning out guide. 

[Emmanuel Bernard]

I would add Kafka based Event Driven Application in this list. This is an important use case for cloud native. 

[Loïc MATHIEU]

The logging guide also needs to be improved, I even think there is already an issue about it.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CANYWk7MRC7PTQjytu-fOGoGWfJHX02FAa7DW65fXzpka%3DgYvAQ%40mail.gmail.com.

[Martin Kouba]

Dne 07. 07. 20 v 11:57 Emmanuel Bernard napsal(a):

> I would repurpose the reference guide to be the getting started guide
> with a reference section. We don’t need more entries per technology.
> Maybe the time will come to need guides that are there but not in the
> menu. So only accessible from an intro fanning out guide.

I tend to disagree. Getting started and reference guide docs have a
different style, structure and flow. Getting started should be short and
easy to navigate even without TOC and chapters are usually read in
sequence. And it's ok to use less formal language and redundant content.
Ref guide on the other hand should be clear and precise and is usually
nagitated through a well-structured TOC. If you combine these two you
will end up with a monster that does not help in any way.

FYI our "brief" CDI ref guide has ~ 1000 lines.

The question of navigation from the website is a completely different
story though.

>
> On Tue 7 Jul 2020 at 08:40, Martin Kouba <mko...@redhat.com

> <mailto:mko...@redhat.com>> wrote:
>
> Dne 06. 07. 20 v 15:56 Emmanuel Bernard napsal(a):
> > Aleatorio, this looks like a good plan to me.
> > I always loved this doc from play framework 1
> > https://www.playframework.com/documentation/1.5.x/guide1 to
> > https://www.playframework.com/documentation/1.5.x/guide12
> > Can you open an issue with your plan and reference. Anyone with
> > different preferences, we can refine the plan. Of course if you have
> > time to start working on this, that would be awesome!
> >
> > Loic, indeed, CDI is too abrupt in its introduction. Can you open an
> > issue so we offer an 2 page intro to CDI in our guide instead of
> > pointing to the spec too abruptly?
>
> I will try to prepare a "CDI getting started guide" this week. The
> current guide is in fact named "cdi-reference" and describes mainly the
> differences between the spec and Quarkus DI (limitations, non-standard
> features, etc.).
>
>
> >
> > The "reference documentation" one is one that people have asked
> (with
> > different definitions) but noone has accepted to pick up so far.
> And I
> > don't think the goal of a reference doc is to make life easier for
> > newcomers.
> >
> > On Fri, Jul 3, 2020 at 8:03 PM Aleatório .
> <lucas....@gmail.com <mailto:lucas....@gmail.com>

> > <mailto:lucas....@gmail.com <mailto:lucas....@gmail.com>>>

> <mailto:emanuel....@gmail.com

> <mailto:emanuel....@gmail.com>>>
> >     wrote:
> >
> >         @Sérgio great idea!
> >         @Loïc sounds great too :)
> >
> >         On Friday, 3 July 2020 17:07:40 UTC+1, Loïc MATHIEU wrote:
> >
> >             @Sérgio, I like what you propose, this could of the
> form of
> >             blog posts and example repos that shows how to integrate
> >             multiple extensions altogether to provide most
> implemented
> >             use cases. Then link them from all the according
> extension
> >             guides.
> >
> >             I created some for "cloud ready" apps with hibernate with
> >             panache, openapi, metrics, ...  But it's in french in the
> >             form of a DOJO.
> >             By the way, having them as a DOJO could also be a
> good idea,
> >             some "Quarkus Katas" repo with explanation of how to
> build
> >             the most typical use cases ...
> >
> >             Le ven. 3 juil. 2020 à 17:58, Sérgio Sousa

> >             <ses...@gmail.com <mailto:ses...@gmail.com>> a écrit :

> >
> >                 I think that, on a beginner level, the structure and
> >                 examples have a good quality. As a user, what I
> miss the
> >                 most is an integration documentation with some
> modules
> >                 (it's not always straightforward to integrate several
> >                 extensions in a bundled project) as this would be the
> >                 ultimate goal of a end user developer.
> >                 Maybe creating some guides for 3 - 4 uses cases
> >                 integrating several modules would improve the
> perceived
> >                 quality of the documentation.
> >
> >                 That being said, I'm an early adopter and appreciate
> >                 very much of everyone's involved!
> >
> >                 Best regards,
> >
> >                 On Fri, 3 Jul 2020, 16:22 Loïc MATHIEU,

> <mailto:eber...@redhat.com>> a écrit :

> > quark...@googlegroups.com <mailto:quark...@googlegroups.com>.

> >                             To view this discussion on the web visit
> >

> https://groups.google.com/d/msgid/quarkus-dev/b2f44ca7-c95c-46da-a3b8-9807e3cab25fo%40googlegroups.com
> >
>  <https://groups.google.com/d/msgid/quarkus-dev/b2f44ca7-c95c-46da-a3b8-9807e3cab25fo%40googlegroups.com?utm_medium=email&utm_source=footer>.
> >
> >                         --
> >                         You received this message because you are
> >                         subscribed to the Google Groups "Quarkus
> >                         Development mailing list" group.
> >                         To unsubscribe from this group and stop
> >                         receiving emails from it, send an email to

> > quark...@googlegroups.com <mailto:quark...@googlegroups.com>.

> >                         To view this discussion on the web visit
> >

> https://groups.google.com/d/msgid/quarkus-dev/CANYWk7Owpw-53sED%3D1_4mj-%2BC3vfGuQvi_zcha2rG2tR8aJ4bg%40mail.gmail.com
> >
>  <https://groups.google.com/d/msgid/quarkus-dev/CANYWk7Owpw-53sED%3D1_4mj-%2BC3vfGuQvi_zcha2rG2tR8aJ4bg%40mail.gmail.com?utm_medium=email&utm_source=footer>.
> >
> >                     --
> >                     You received this message because you are
> subscribed
> >                     to the Google Groups "Quarkus Development mailing
> >                     list" group.
> >                     To unsubscribe from this group and stop receiving
> >                     emails from it, send an email to

> > quark...@googlegroups.com <mailto:quark...@googlegroups.com>.

> >                     To view this discussion on the web visit
> >
> https://groups.google.com/d/msgid/quarkus-dev/CAJLxjVHFZG%2B2009iV5kmyT3snLj3HkOVMQgrkyZw_CGGdbpfrQ%40mail.gmail.com
> >
>  <https://groups.google.com/d/msgid/quarkus-dev/CAJLxjVHFZG%2B2009iV5kmyT3snLj3HkOVMQgrkyZw_CGGdbpfrQ%40mail.gmail.com?utm_medium=email&utm_source=footer>.
> >
> >         --
> >         You received this message because you are subscribed to the
> >         Google Groups "Quarkus Development mailing list" group.
> >         To unsubscribe from this group and stop receiving emails from
> >         it, send an email to
> quarkus-dev...@googlegroups.com

> <mailto:quarkus-dev%2Bunsu...@googlegroups.com>
> >         <mailto:quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev%2Bunsu...@googlegroups.com>>.

> >         To view this discussion on the web visit
> >
> https://groups.google.com/d/msgid/quarkus-dev/ee96735a-5ea7-4708-a4cc-531af4d2cd0ao%40googlegroups.com
> >
>  <https://groups.google.com/d/msgid/quarkus-dev/ee96735a-5ea7-4708-a4cc-531af4d2cd0ao%40googlegroups.com?utm_medium=email&utm_source=footer>.
> >
> >
> >
> >     --
> >     Att.
> >
> >     João Lucas Scharf, o Aleatório
> >
> >     --
> >     You received this message because you are subscribed to the
> Google
> >     Groups "Quarkus Development mailing list" group.
> >     To unsubscribe from this group and stop receiving emails from it,
> >     send an email to quarkus-dev...@googlegroups.com

> <mailto:quarkus-dev%2Bunsu...@googlegroups.com>
> >     <mailto:quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev%2Bunsu...@googlegroups.com>>.

> >     To view this discussion on the web visit
> >
> https://groups.google.com/d/msgid/quarkus-dev/CAHzqWS7LSJ37K-vjJ3SLnhYqS1hfF4c%2BG-D%2B0qr9X-9EUzCsaA%40mail.gmail.com
> >
>  <https://groups.google.com/d/msgid/quarkus-dev/CAHzqWS7LSJ37K-vjJ3SLnhYqS1hfF4c%2BG-D%2B0qr9X-9EUzCsaA%40mail.gmail.com?utm_medium=email&utm_source=footer>.
> >
> > --
> > You received this message because you are subscribed to the Google
> > Groups "Quarkus Development mailing list" group.
> > To unsubscribe from this group and stop receiving emails from it,
> send
> > an email to quarkus-dev...@googlegroups.com

> <mailto:quarkus-dev%2Bunsu...@googlegroups.com>
> > <mailto:quarkus-dev...@googlegroups.com
> <mailto:quarkus-dev%2Bunsu...@googlegroups.com>>.

[James Cobb]

I agree with adding a quick start section to the Guides page (I included them on the updated Guides wireframes).

https://xd.adobe.com/view/90b1aeb0-4441-475b-7cb0-bf2a80a1a11b-e680/screen/5cc3b78d-7df1-4b47-9b0b-b680e2e24501

James

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAJLxjVEoajPhLPwqKGhN%3DXie3dHFJX%2B32KYhx0d8fUz8Zi5pAA%40mail.gmail.com.

[Abel Salgado Romero]

Has multi-language support been considered?

The drawbacks are many in terms of maintenance, but should not be hard to set the site to support guides in multiple languages and would help making docs more accessible for some people.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/274A715A-763B-4421-8DCD-488EB6DC1046%40redhat.com.

[Yans]

I believe its good to have separate Getting started and Reference docs.

An all encompassed reference doc with ToC (something like Flask Micronaut Jooby Jdbi) will be quite useful. The entire content in one page (with ToC on left) has some advantages too, that it makes it easy to search for something (for eg: 'session') within the page and see all the sections it touches upon, else I'd need to click through all ToC links.

Few comments from UI/UX perspective on the current https://quarkus.io/guides/

1. Column 2 has all the links from 'Core' repeated. eg: Configuring Your Application is in the ToC column as well as 'READ THE GUIDE' under Configuring Your Application. Its redundant and confusing.
2. The name 'Core' is bit vague, doesn't really give a clear mental model what it represent.
3. Same goes with 'Observability', its enterprisy. Perhaps, 'Monitoring' would de a better job?
4. In the column 2, the repeated boxed 'READ THE GUIDE' format is bit odd, take way attention from the rest of the pages.
5. Clicking on the link will take to a new page/guide and you lost the ToC, you have to click on the back button on the browser to get back. Not a good UX in my opinion.
6. Font size of the content and links are bit big for my taste.

It may be because its purported as Guide instead of Ref Doc. But if we can repurpose it as Reference doc with two column (Toc + Content), that would give a nice navigation model without any friction.

Thnx

[Michael Schnell]

+1 for an overall reference doc like https://docs.wildfly.org/20/

Font size of the content and links are bit big for my taste.

I disagree with this. A good design should also consider visual accessibility for older or visually impaired people.

The font size should not be too small and also black text color on white background is a must.

[Stuart Douglas]

On Mon, 13 Jul 2020 at 22:16, Yans <s.val...@gmail.com> wrote:

I believe its good to have separate Getting started and Reference docs.

We have had lots of discussions about this, and there are definitely conflicting opinions.

Personally I agree that we should have a reference guide that is separate to the getting started guides. IMHO getting started guides should be a walkthrough of the quickstart, and then should link to the relevant section of the reference guide.

From an alternative perspective I think this is also much better as a developer of Quarkus. Say I add a feature such as my recent 'test profiles' feature. At the moment if I want to document this I have a couple of choices:

- Write a whole new guide about it. This option sucks, it is a lot of work for basically a couple of paragraphs of actual content. Guide per feature also means that our documentation page will end up with a massive number of guides so it will be hard to find what you want, and once you have read a few guides they all end up repeating themselves with all the setup stuff, so the signal/noise ratio is too low.

- Add it to the getting started guide. This is basically the approach we have taken, but now the 'getting started guide' is slowly turning into a testing reference doc.

- Don't document it. I think this actually happens more than what it should just because with our current arrangement there is often nowhere that makes sense to put the documentation. For example the new fast-jar format should be documented somewhere, but where? It definitely does not need its own guide, but it makes no sense to put in it our existing guides. I could write a new 'packaging reference' but that is yet another link on our docs page, and it is probably not going to be obvious to users what it actually is.

I think we should have a very strict distinction:

Guides are our current walkthroughs that hold your hand through how to get started with a given technology. I think we actually need to expand these somewhat, as at the moment we assume that users know about Jakarta EE technologies like JAX-RS and CDI. There should mostly be a 1:1 mapping between quickstarts and guides (maybe the guides should even live in the Quickstart repo, so they can stay in sync easier?).

The reference guide is compiled into one big document, and has pretty much everything else. This means that if a user is looking for something and they are not 100% sure where it might be then they can use Ctrl+F, and as a Quarkus developer there is an obvious place to document anything I am working on. Guides should link to the relevant section of the reference doc at the end of the guide, so the user can continue learning.

Stuart

 

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/be1628d3-5d35-46c1-8a04-df2d506081b0o%40googlegroups.com.

[Emmanuel Bernard]

For having done it in the past, multi lingual support is really really hard to maintain in the long run. There is often a heroic effort by a contributor for a language and then things die out.

[Emmanuel Bernard]

To be honest I don't see our guides as getting started but as sections of a reference guide. with a quick start at the beginning of each.

So looking at Yans examples of good reference guides, they really seem to be our guides in one big page (if you remove the quickstarts).

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAD%2BL2czkF-rugaGy1q0Ee9GcbQjXT-_ZZB0fOAJ%3DttdJJ4fb6g%40mail.gmail.com.

[Jaikiran Pai]

On 14/07/20 6:49 am, Stuart Douglas wrote:

On Mon, 13 Jul 2020 at 22:16, Yans <s.val...@gmail.com> wrote:

I believe its good to have separate Getting started and Reference docs.

We have had lots of discussions about this, and there are definitely conflicting opinions.

Personally I agree that we should have a reference guide that is separate to the getting started guides. IMHO getting started guides should be a walkthrough of the quickstart, and then should link to the relevant section of the reference guide.

From an alternative perspective I think this is also much better as a developer of Quarkus. Say I add a feature such as my recent 'test profiles' feature. At the moment if I want to document this I have a couple of choices:

- Write a whole new guide about it. This option sucks, it is a lot of work for basically a couple of paragraphs of actual content. Guide per feature also means that our documentation page will end up with a massive number of guides so it will be hard to find what you want, and once you have read a few guides they all end up repeating themselves with all the setup stuff, so the signal/noise ratio is too low.

- Add it to the getting started guide. This is basically the approach we have taken, but now the 'getting started guide' is slowly turning into a testing reference doc.

- Don't document it. I think this actually happens more than what it should just because with our current arrangement there is often nowhere that makes sense to put the documentation. For example the new fast-jar format should be documented somewhere, but where? It definitely does not need its own guide, but it makes no sense to put in it our existing guides. I could write a new 'packaging reference' but that is yet another link on our docs page, and it is probably not going to be obvious to users what it actually is.

Here's one example of there being no definitive place to add/find (small) feature specific documentation right now https://github.com/quarkusio/quarkus/issues/10815

-Jaikiran

[Emmanuel Bernard]

Well it just seems that we need a Podman entry in the guide the user was looking for, that's it. It's about two different usages anyways, so being documented in different places is fine

--

You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/20e31997-1c3b-337b-e65d-d589e7caa4bb%40gmail.com.

[Julio Henrique Morimoto]

Coming up late to this thread. But I'd to agree. In fact, official docs lack even more than just guides and examples for beginners.

I consider myself an experienced developer (15+ years between dev and sysadmin roles), and I'm still unable to find any explanations on how Quarkus actuall works! I mean... what is it goind under the hood? I get the summary point. It makes java applications more efficient and more suitable for containers, cloud, kubernetes, serverless. But how??? Reading official docs, I have no idea. All I see are basic examples and the intuitive promise that it works.

My company's dev teams are prospecting new tools and frameworks for application development. But honestly, I can't even form an opinion about Quarkus. It's a blackbox. Help is this matter is appreciated.

Best regards.

[Stuart Douglas]

On Sun, 27 Sep 2020 at 02:27, Julio Henrique Morimoto <j...@juliohm.com.br> wrote:

Coming up late to this thread. But I'd to agree. In fact, official docs lack even more than just guides and examples for beginners.

I consider myself an experienced developer (15+ years between dev and sysadmin roles), and I'm still unable to find any explanations on how Quarkus actuall works! I mean... what is it goind under the hood? I get the summary point. It makes java applications more efficient and more suitable for containers, cloud, kubernetes, serverless. But how??? Reading official docs, I have no idea. All I see are basic examples and the intuitive promise that it works.

My company's dev teams are prospecting new tools and frameworks for application development. But honestly, I can't even form an opinion about Quarkus. It's a blackbox. Help is this matter is appreciated.

The extension authors guide contains some details on how it works, but maybe we should have a 'how it works' type document.

Stuart

 

Best regards.

Em segunda-feira, 20 de julho de 2020 às 05:55:15 UTC-3, eber...@redhat.com escreveu:

Well it just seems that we need a Podman entry in the guide the user was looking for, that's it. It's about two different usages anyways, so being documented in different places is fine

On Mon, Jul 20, 2020 at 8:10 AM Jaikiran Pai <jai.for...@gmail.com> wrote:

On 14/07/20 6:49 am, Stuart Douglas wrote:

On Mon, 13 Jul 2020 at 22:16, Yans <s.val...@gmail.com> wrote:

I believe its good to have separate Getting started and Reference docs.

We have had lots of discussions about this, and there are definitely conflicting opinions.

Personally I agree that we should have a reference guide that is separate to the getting started guides. IMHO getting started guides should be a walkthrough of the quickstart, and then should link to the relevant section of the reference guide.

From an alternative perspective I think this is also much better as a developer of Quarkus. Say I add a feature such as my recent 'test profiles' feature. At the moment if I want to document this I have a couple of choices:

- Write a whole new guide about it. This option sucks, it is a lot of work for basically a couple of paragraphs of actual content. Guide per feature also means that our documentation page will end up with a massive number of guides so it will be hard to find what you want, and once you have read a few guides they all end up repeating themselves with all the setup stuff, so the signal/noise ratio is too low.

- Add it to the getting started guide. This is basically the approach we have taken, but now the 'getting started guide' is slowly turning into a testing reference doc.

- Don't document it. I think this actually happens more than what it should just because with our current arrangement there is often nowhere that makes sense to put the documentation. For example the new fast-jar format should be documented somewhere, but where? It definitely does not need its own guide, but it makes no sense to put in it our existing guides. I could write a new 'packaging reference' but that is yet another link on our docs page, and it is probably not going to be obvious to users what it actually is.

Here's one example of there being no definitive place to add/find (small) feature specific documentation right now https://github.com/quarkusio/quarkus/issues/10815

-Jaikiran

--

You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/20e31997-1c3b-337b-e65d-d589e7caa4bb%40gmail.com.

--
You received this message because you are subscribed to the Google Groups "Quarkus Development mailing list" group.
To unsubscribe from this group and stop receiving emails from it, send an email to quarkus-dev...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/949eaa7b-87e6-4ddd-9ef5-3a6539417999n%40googlegroups.com.

[Antonio Goncalves]

Hi all,

I agree with Julio: I miss a nice architecture diagram showing the main internal components and interactions. For example, the kind of diagrams you find[1] tend to highlight the extensions, but not the extension mechanism (I first thought the extension mechanism was based on JBoss Modules). Jandex comes into the play, but we don't really see by which internal component it is used. Same for Vert.x, Netty, Undertow (which sometimes is used internally), etc.

It would be nice to have a "Quarkus from the trenches" kind-of documentation on Quarkus internal mechanisms.

My 2 cents

Antonio

[1] http://www.mastertheboss.com/soa-cloud/quarkus/getting-started-with-quarkus

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/949eaa7b-87e6-4ddd-9ef5-3a6539417999n%40googlegroups.com.

--

Antonio Goncalves 
Contractor, Java Champion and Pluralsight author

Blog | Twitter | LinkedIn | Author | Pluralsight | Devoxx France | Voxxed Microservices

[Emmanuel Bernard]

Can you open an issue so we can track and put on the roadmap?

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CAKawoObMv6b3i2P%2BA57B7mLNVmO6Q%2Btcm5u_x0CESA2royQEPw%40mail.gmail.com.

[Antonio Goncalves]

Here it is : https://github.com/quarkusio/quarkus/issues/12400

To view this discussion on the web visit https://groups.google.com/d/msgid/quarkus-dev/CANYWk7MJuqT-ZPuj_dmKuRvVEMd7MhWT-UwjHWODEXw56a7sOQ%40mail.gmail.com.