alpaka documentation? (Linking the master's thesis as documentation somewhere)

[theZiz]

I just noticed, that you do not really link your master thesis in the README.md or somewhere else except for a bibliography-snippet, from where someone could copy the link, but this is not very obvious.

Imo it would be a good idea to directly refer to it as documentation as it is the most useful help for a new user atm - even if it may be outdatet because of recent API changes.

[BenjaminW3]

@ComputationalRadiationPhysics/alpaka-maintainers What is your opinion? Should we link it more prominently? Is the link within the citation enough because the master`s-thesis is already out-of-date on some topics?

[ax3l]

I say: wiki it! :)
enough space to list and explain details like:' "xyz" is now removed, see publication "abc", etc.'

[BenjaminW3]

The main reason for not using the wiki was that I would have had to update my thesis and the wiki everytime I changed something. Therefore I decided to go thesis only.
Now that the thesis is long finished and in parts outdated I think that it should not be promoted as documentation.

Nevertheless, we should extract and update the information from the thesis and bring it online.
However, I do not want the wiki to be a necessary second place to find the information. I would much more prefer the alpaka repo itself as a single source of truth. Somebody who clones/downloads the repo should always be able to access the documentation exactly for this version without requiring internet access. The doxygen docu can be generated from the source and the rest should be available as plain files. Furthermore, a search and replace (renaming, etc.) within the repo should automatically update the documentation.

My preferred solution are Markdown files directly within the doc/ subdirectory. The index.md file could be linked directly from the ReadMe.md and contain links to all other documentation files. The wiki would be removed completely. I would even volunteer to do this.

There would be a way to have both, wiki and markdown within the repo by adding the wiki repository as a subtree/submodule within doc/wiki/. Though there are problems and complications with both of those variants. (How to keep them _always up-to-date_ but _without user action_ even when the _wiki is changed from within github_?)

[ax3l]

I think that is the right way to go.

What I was suggesting is a listing of historic references with notes such as "up to date until v0.2.0", "superseded since v0.3.0 by the concept of ..." - putting those in a in-repo .md file would be even better, yes.

[ax3l]

Btw, you could also go the other way around as we do it with doxygen: generate auxiliary helps/manuals _from_ the main repo. But I think that is optionsl since markdown support on github works great.

[BenjaminW3]

Documentation is now available!

[theZiz]