Documentation is less helpful than it could be

[noelwelsh]

The documentation for sbt-native-packager is generally IMO less helpful than it could be. It often fails to describe what is going on in any detail. For example:

http://www.scala-sbt.org/sbt-native-packager/formats/universal.html#configurations

"Here is how the values for name and packageName are used by the three configurations:"

Why are you stating this? (Don't tell me in this issue---update the documentation!) How are name and packageName interpreted in the context of packaging? They don't appear to relate to the name of the generated output file, so what do they do?

http://www.scala-sbt.org/sbt-native-packager/formats/universal.html#settings

I would expect this section to describe what each setting that the universal package relies on. Instead if just gives an example that doesn't even explain. Why did you give the example mappings in Universal <+= packageBin in Compile map { p => p -> "lib/foo.jar" }? What does it do? What point are you trying to make? I don't know because you didn't tell me.

The rest of the documentation is similar. In my case I'm trying to simply change the name of the outputted zip file, and I've spent over an hour without success.

[muuki88]

Thanks @noelwelsh for you feedback on the documentation. I'm sorry if it caused more trouble than answering questions. Some parts of the documentation are pretty old and we reliy heavily on the community to update it (e.g. for newer sbt versions or best practices).

How are name and packageName interpreted in the context of packaging? They don't appear to relate to the name of the generated output file, so what do they do?

Thanks for pointing this out. These settings aren't documented. The only reference is here: https://github.com/sbt/sbt-native-packager/blob/master/src/main/scala/com/typesafe/sbt/packager/Keys.scala#L11

I would expect this section to describe what each setting that the universal package relies on. Instead if just gives an example that doesn't even explain

The universal plugin documentation is really not up-to-date. Is the Debian Plugin settings documentation more like what you would have expected?

The rest of the documentation is similar. In my case I'm trying to simply change the name of the outputted zip file, and I've spent over an hour without success

The packageName is the correct setting to change the output file. See this scripted test.

There is also a repository with some examples: https://github.com/muuki88/sbt-native-packager-examples

I'm happy to merge any documentation improvements and open for any concrete suggestions (like the two examples above) to improve the documentation. This is an open source project and most of the work is done by the community or in my free time :)

[tobyweston]

I might be able to chip in with some documentation, can you outline where the source is? I couldn't see anything obvious in < the 4 mins I scanned the repo.