Add directory path clarity to Quickstart Tutorial for new users

[katcaola]

I'm a new user to OSGi and I was very confused where to run commands specified in the quickstart tutorial.

In a lot of tech tutorials I've seen, there is a directory path shown before the $ <CLI COMMAND> such as directory/path/location $ ls .. This helps prevent confusion about where to run CLI commands.

One issue that took me at least a day to resolve was that the quickstart tutorial told me to run commands in the examples/quickstart dir but never told me to run commands anywhere else.

When it came time to recreate the project using OSGi I didn't know that I had to run the project template command outside of the project I had just downloaded.

user@host:~/sandbox/osgi.enroute/examples/quickstart/quickstart $ mvn org.apache.maven.plugins:maven-archetype-plugin:3.0.1:generate \
-DarchetypeGroupId=org.osgi.enroute.archetype \
-DarchetypeArtifactId=project \
-DarchetypeVersion=7.0.0
user@host:~/sandbox/osgi.enroute/examples/quickstart/ $ ls 
app  pom.xml rest quickstart

Since I'm not very mvn savvy, I was confused when issues came up about repeated parent.artifactId since I was following the instructions exactly as specified.

[INFO] Scanning for projects...
[ERROR] [ERROR] Some problems were encountered while processing the POMs:
[FATAL] 'parent.artifactId' must be changed, the parent element cannot have the same
 groupId:artifactId as the project. @ org.osgi.enroute.examples.quickstart:quickstart:1.0-SNAPSHOT,
 /home/user/sandbox/osgi.enroute/examples/quickstart/quickstart/pom.xml, line 5, column 17

I would clarify where to run commands for future users by adding detail to the CLI command code snippets:

~/osgi.enroute/examples/quickstart $ mvn verify

~/osgi.enroute/examples/quickstart $ java -jar app/target/app.jar

~/sandbox $ mvn org.apache.maven.plugins:maven-archetype-plugin:3.0.1:generate \
-DarchetypeGroupId=org.osgi.enroute.archetype \
-DarchetypeArtifactId=project \
-DarchetypeVersion=7.0.0

Having created the project skeleton, edit ~/sandbox/quickstart/impl/src/main/java/org/osgi/enroute/examples/quickstart/rest/ComponentImpl.java

Etc.

[timothyjward]

That looks good to me, as long as we can make sure that the commands are still readable (sometimes the text overflows the side of the page in an awkward way when displaying the commands).

Teel free to create a pull request with the changes.

[katcaola]

@timothyjward Would it be alright to have the commands include line continuation symbols? When they are rendered on the website it appears as

~/microservice $ mvn archetype:generate \
      -DarchetypeGroupId=org.osgi.enroute.archetype \ 
      -DarchetypeArtifactId=ds-component \
      -DarchetypeVersion=7.0.0

And these can be run if the commands are directly copy/pasted (on linux cli environments)

The downside is this might confuse users who are using non-linux based command lines. I could always put a note about making sure to change the line continuation symbol based on your OS?

[timothyjward]

That looks fine to me

I could always put a note about making sure to change the line continuation symbol based on your OS?

A description of the continuations would be a good thing to add in the prerequisites page. There's also a section on OS specifics which could be used to say what (if anything) different you need to do on Windows/Mac. Putting information there should hopefully avoid us having to call it out every time.

[katcaola]

Fixed With Commit #199