search

metafacture / metafacture-core

Core package of the Metafacture tool suite for metadata processing.
https://metafacture.org
Apache License 2.0
71 stars 34 forks source link

Inconsistency in manual for distribution installation #408

Open TobiasNx opened 2 years ago

TobiasNx commented 2 years ago

https://github.com/metafacture/metafacture-core#building-metafacture-core-from-source says to use: $ ./gradlew install

https://github.com/metafacture/metafacture-core/wiki/Flux-user-guide#installing-flux says to use: ./gradlew installDist

Which is right? Should be consistent in documentation

blackwinter commented 2 years ago

In a way, they're both correct. It's basically the difference between "Using Metafacture as a Java lib[r]ary" and running "Metafacture as a stand-alone application". But I agree that it could be clarified in the documentation.

dr0i commented 2 years ago

As @blackwinter noted the difference is that ./gradlew install also provides files into the developer's local maven repository to be used as a java library. I've added re: "local maven repository" to the README and simplified/rephrased the flux-wiki (without explicitly noting there that ./gradlew installDist doesn't provide local maven builds to not confuse the non-developing user with unnecessary information.) Provides this more clarity @TobiasNx ?

TobiasNx commented 2 years ago

Hi @dr0i, i still think that this is confusing as well as redundant in a way since there are two installation guides. Or do I miss the point.

We have two variations of metafacture (standalone and as java lib) and each of these variation has a version that is build from release or from a branch. 

Installation:
- Standalone
- - Release
- - Branch
- Java-Lib
- -Release
- -Branch

This is perhaps something for the documentation improvement.

dr0i commented 2 years ago

Hm, I don't see inconsistencies here - but let's try to fix the confusion. Maybe your view of just an "installation" guide is not quite that proper in that respect that many READMEs provide an "Installation" AND a "Usage" section. The latter provides only the flux-wiki page.

I think we should in general keep the README rather short (that's more of an effort because we have Flux and pure java resp. library).

a) Maybe we should provide an usage example for both (flux and java) in the README , or/and maybe we should also add a wiki-page for java installation and usage like for the flux (I vote for both proposals with a short java code example and a corresponding flux in the README).

Let's go into more details here to explain why a) may be a good solution:

The flux wiki page states in the first paragraph:

Metafacture as a stand-alone application

So there are mostly non-developers addressed (well, for completeness sake it's also mentioned how to use the Flux from/as a Java class (3.1) So you see that the dichotomy of "stand-alone" and "non-programmer" is not quite true if it comes to comprehensiveness (why do you want to use Flux.java ? E.g. if you want to debug a flux workflow).

In the README I just added a link to the comprehensive flux wiki page (27780befa4b3fceea7ef7f01348cb811f1ed6e80) without removing the (redundantly) short introduction in the README of how to install flux stand-alone, so users still have a quick overview there of what's possible.

For developers the README explains just how to:

  1. use the Java libary as a maven project (by configuring maven central releases in the pom)
  2. how to build your own branch and install it into the local maven repository

If I gather that correctly you would rather want to have just one page (the README then) where these different kinds of installations and usages are described. I think it would be too much in the README to add the comprehensive (and even more exapandable) flux-how-to (aka the wiki page), but I am good with a proposal like b) "let's put just a link in the README to the flux wiki page instead of have some guide redudantly").

As noted above, the installation guide in the README comes short of a (comprehensive) usage (with examples and so on) for using ~metamorph~ metafacture as a library. There is not even a (direct) link to an example. The experienced coder may have a look in the test directories but I agree that something like https://github.com/hbz/metafacture-java-examples/blob/master/src/test/java/samples/Sample1_PrintData.java would be nicer (whereas https://github.com/hbz/metafacture-java-examples I don't like for when clicking on "src/main/java" the directory is empty which is confusing).

So yeah, we have a lot to restructure/link re docu in general.

Let me ask, how are you confused exactly (from the perspective of a non-programmer) in using metafacture starting from the repo's README ? And what about proposal a) an/or b) or maybe you have some alternative proposal?