search

osgi / osgi.enroute.site

GitHub Pages repo for OSGi enRoute website
https://enroute.osgi.org/
Apache License 2.0
18 stars 54 forks source link

Minor grammar fix #190

Closed Weltraumschaf closed 5 years ago

Weltraumschaf commented 5 years ago

Currently I'm reading through the side and stumbled upon this missing pronoun.

The remove of trailing spaces was automatically done by Markdownlint (I recommend this tool) in my editor.

bjhargrave commented 5 years ago

This change is fairly minor but you should get in the habit and amend your commits so that each commit message includes a Signed-off-by as required by CONTRIBUTING. Then push force your updated commits. Thanks.

Weltraumschaf commented 5 years ago

Ups, sorry. Didn't read the CONTRIBUTION.md.

A question about the examples in the text: For me as OSGi novice, it would be nice to also have the import ... parts in the example code. For beginners it may hard to find out the right imports. What do you think about that?

timothyjward commented 5 years ago

A question about the examples in the text: For me as OSGi novice, it would be nice to also have the import ... parts in the example code. For beginners it may hard to find out the right imports. What do you think about that?

This is a difficult balance to strike. While adding the import statements makes it easier to copy/paste/run the code it also makes it much harder to read and explain on the web. We try to make sure that the site is readable on a variety of devices, and that it's clear which bits of the example code are important. Obviously the import statements are important to the compiler, but they're rarely (if ever) important to a person reading the site.

So far our internal guideline is that tutorial snippets, for example here in the microservice tutorial, which are intended to be copy/pasted by the reader are complete and copied from the real source by the build. All other snippets omit package/import declarations, and sometimes class/method declarations to focus on the important part of the code.

If the consensus is that this guideline needs to change then that's great. I'm just trying to make sure that we are all aware of the potential downsides.

Weltraumschaf commented 5 years ago

Ok, thanks for the answer. I'm just reading through the whole site and saw that there is also the pattern to link to a full example. Something like that would be also sufficient for a beginner.

bjhargrave commented 5 years ago

Thanks!