Add some descriptive documentation

[laeubi]

Currently it is very hard to getting started (or even recommending to others) osgi-test as you mostly has to puzzle things together:

1. https://osgi.github.io/osgi-test/ is just a dummy page with no content
   2.the wiki only references the examples but they are not really self-contained (e.g. the reference project-version) so its hard to tell how to setup an own test-case.
2. beside that, the examples are rather undocumented the classes it self have no documentation why certain things are used and why they work that way (only package-info has some vague hints how it is supposed to work)
3. the slides gives a rough overview over the goals and how it could be used but not much details about setup and/or internals

I think it would really help to enhance the documentation with at least the following information:

1. What is a minimal maven setup/quickstart for Juni 4 + Junit 5 so people can simply c&p it into their pom and getting started.
2. How osgi-test works internally e.g. how does it discover items, what needs to be provided via maven dependencies
3. describe for example the "usefull utils" in org.osgi.test.common in more details
4. ...

[kriegfrj]

Hi @laeubi , thanks for the feedback!

Have you seen the documentation in the readmes? See here: https://github.com/osgi/osgi-test

Maybe we can do a better job of linking it to the rest of the doc.

Also, some of your questions seem to go a bit beyond the scooe of the osgi-test library and are more directed at writing code/tests under OSGi in general. Perhaps we could link to relevant sources as prerequisites.

[laeubi]

Have you seen the documentation in the readmes?

Yes but those are more examples that already "jump into the topic", just as an example there is no direct hint:

1. what maven dependencies are required?
2. what is the current released version?
3. Can I run my tests inside the module under test?
4. Do I need BND / RCP /... to run my test or is surefire enougth

While this might be obvious for people using osgi-test already its hard for newcomers, and for sure some things a more generic but it would help to have something like https://github.com/junit-team/junit5-samples/blob/r5.8.2/junit5-jupiter-starter-maven/pom.xml for example as a (linked) reference, so lets say I have no idea about juni5 I can still copy the pom and at laest know that all dependencies are set.

To stay with this example JUnit 5 has a quite descriptive overview for beginners here:
https://junit.org/junit5/docs/current/user-guide/

So I can get a fast overview about the What/How and some links that directly guide me to more detailed aspects.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. If you feel this is something you could contribute, please have a look at our Contributor Guide. Thank you for your contribution.

[laeubi]

Still only dummy content on that site, examples are hard to understand and fragmented documentation.

In the meanwhile i learned junit seem to use asciidoc for their documentation what gives a really nice looking result and can easily be deployed to github pages.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. If you feel this is something you could contribute, please have a look at our Contributor Guide. Thank you for your contribution.

[laeubi]

Still no content...