contribution: update documentation with new plugin ids

[pdeschen]

Since I got bitten by invalid plugin ids while reading the doc, I thought I would contribute the documentation first with updated plugin ids.

You can find my update over https://github.com/pdeschen/wuff-wiki

I did a simple one liner over all plugin ids.

for I in *.md ; do sed -i '' -e "s/apply plugin: 'swt-lib'/apply plugin: 'org.akhikhl.wuff.swt-lib'/g" $I; done

I've also added a section in the Home.md about contributing.

Note: Unfortunately, github do not support pull request on wiki repo, so you'll need to go old school :-)

[akhikhl]

Very good, I will incorporate your changes :) I also thought of moving doc from wiki to a separate repository, same way as I already did for gretty project:

• doc sources: https://github.com/akhikhl/gretty-doc
• compiled doc: http://akhikhl.github.io/gretty-doc/

I even created https://github.com/akhikhl/wuff-doc repository, but it requires lot of work: conversion from github markdown to asciidoc.

[pdeschen]

I just did some more edits :-)

Just out of curiosity, what are the advantages of having a separate repo for the doc? github wiki is already backed by a git repo.

[akhikhl]

I merged your edits, thank you so much :)

Hint on how you can sync both to akhikhl/wuff.wiki.git and pdeschen/wuff-wiki.git:

cd wuff-wiki
git remote add upstream git@github.com:akhikhl/wuff.wiki.git
git pull upstream master
git push

upstream isn't keyword, it is just a name for remote repo.

I made symmetric setup on my computer, so I can pull your changes and push them to akhikhl/wuff.wiki.git.

Separate repo for doc - four reasons:

1. As you already mentioned, there's no Pull-Request mechanism for github wiki. With separate repo we have such mechanism, so merges are much easier.
2. As documentation gets more and more complex, it's necessary to organize navigation menu. I find the sidebar navigation (provided by github wiki) being suboptimal.
3. The layout of github wiki is too narrow for some multi-column tables. Have a look: http://akhikhl.github.io/gretty-doc/Gretty-tasks.html.
4. When doc includes images (would it be png, jpeg, svg), they need to be hosted somewhere. I tried placing images in the same wiki repo - it did not work. Clogging main repository with doc-specific files is also suboptimal.

[pdeschen]

Thanks for the clarification about the doc in a separate repo. Make sense for larger project which is the case for wuff.

As for your hint on syncing repos, it won't work as I'm not authorized to push directly onto your upstream. And that's ok. You certainly don't want me to push to your master without review :-)

[akhikhl]

You can at least pull from my repo and push to yours. And, on your request, I can pull from yours and push to mine. This is how it should work for now :) I will see to completely migrating doc to a separate repo in the next days. Then things get simpler.

[pdeschen]

Indeed!