Convert README+CONTRIBUTION to Markdown, include rendered HTML version

[simon04]

For a better display on ​GitHub and in the about dialog, I propose to

• convert README and CONTRIBUTION to Markdown
• compile those files to HTML during the Ant build using ​https://github.com/atlassian/commonmark-java
• display the HTML version in the about dialog

What do you think?

[GerdP]

No idea, I've just learned that the extension .md means MarkDown :)

[stoecker]

Little benefit, but much additional work. Markdown is more or less a GitHub format and makes not much sense elsewhere.

[simon04]

Markdown is everywhere. Markdown is also supported by GitLab: ​https://docs.gitlab.com/ce/user/markdown.html

If README is meant for reading, it should be displayed in a visually appealing form.

[simon04]

Here's an example how appealing the README could be rendered (on JOSM's GitHub repository, for instance): ​https://github.com/wolfv/josm/blob/master/README.md

[stoecker]

Why should we? If we want it fancy we long could have copied it to the wiki like all the other more detailed information about JOSM and JOSm development. It is not the purpose of this file to be fancy, but to be a compressed information about the sources.

[simon04]

Many people (including me) (almost exclusively) browse GitHub to find FOSS projects to use and to contribute to. A clear and visually appealing README is key to attract attention and transport the initially relevant information to users and contributors.

In my opinion, the project setup of JOSM is not a very attractive/friendly/intuitive for new contributors, in particular due to the many ancient technologies used.

[GerdP]

I don't see how a picture in the readme changes the project setup. I agree that the setup is not very intuitve. I don't understand why ancient technologies are a problem as long as ancient means well known. Maybe that's because I made my living coding software for IBM z/OS mainframes, formerly known as OS/390 or MVS and still backward compatible. For me, noew technologies often mean solved old but well known problems and unsolved new problems ;)

[stoecker]

I don't want to attract people "browsing GitHub to find FOSS projects to use and to contribute to". I want people who are interested in the software itself. People only interested in the technology often do more harm than good. E.g. you want to change the preferences dialog and do a lot of work, but at the end Vincent needs to do cleanup so that we can have a new release again somewhen. Sorry, but that's nothing which I want to encourage at all.

If people only contribute when we use the newest buzzword technologies then I'm happy when they do not contribute. I know a lot of other projects which attract students and newcomer developers and what I see there is that they rewrite code, redesign functions, rework everything but the software does not get better, only different. E.G. For KDE I see that for each generation everything gets redone and it looks fancier, but functionality is the same as for earlier versions (even some things which I heavily used in the past are still missing).

That's not the way I want JOSM to be.

I'm doing software development for 30 years now. I wrote programs in more than a dozen programming languages, used more than half a dozen source code control sources, dozens of bug tracker systems, markup languages, build systems, and so on and so on. Sometimes they are better sometimes not. Much more important than the technology is if it works or not. And for JOSM our currently technology works very well (I'm not so sure about some new stuff like ivy f.e.).

I'm open to change technology when the new one has clear advantages. But to make it totally clear: I will not support any new technology for the sole purpose of having a new technology!

[simon04]

E.g. you want to change the preferences dialog and do a lot of work, but at the end Vincent needs to do cleanup so that we can have a new release again somewhen.

There seems to be a misunderstanding:

I've addressed the "what should be done before next release" from ticket:7548#comment:117 and refrained from further changes from "what should be done, but is not a blocker for release" in order to have some sort of stabilisation before the release. As this ticket has shown, there is an endless stream of new ideas once you open the can of worms.