First documentation pages

[hartig]

As a first set of documentation pages for potential users of HeFQUIN (users != developers who want to work on HeFQUIN itself), we need the following pages.

• How to start the Web service via Docker, change the federation description that it uses, and how to issue queries to the service.
• How to start the Web service from the latest release package, change the federation description that it uses, and how to issue queries to the service.
• How to run queries using the CLI tool in the latest release package, including a detailed description of the arguments of the CLI tool.
• How to run queries using the latest source code version of the CLI tool or the Web service.
• How to specify the federation to be queried, including a documentation of the most important parts of the RDF vocabulary defined for this purpose.
• Additionally, we need to create a README.txt file that we put in the top-level directory of the release packages and that contains a short version of these points above, including pointers to the respective documentation pages.
• A similar summary of these points needs to be added to the README.md of the repo.

/cc @keski

[keski]

I've added a first version of the usage summary to the README.md in the issue branch.

@hartig Is this on a good level of detail or did you have anything else in mind?

[keski]

For the detailed instructions I assume we will be using the wiki?

[hartig]

I've added a first version of the usage summary to the README.md in the issue branch.

Which branch exactly? Is (or was) this in a PR?

For the detailed instructions I assume we will be using the wiki?

This question is related to one of the two proposals that I wanted you to work out (see my Malaga follow-up email).

[keski]

Okay, I viewed the two as separate issues but now I see your point. I'll respond by email.

The branch I referred to with updated README is 346-first-documentation-pages.

[keski]

I've copied and updated the instructions from the wiki and added them to the web page. Instead of linking to the source code, the class and package references are now linked to the Javadoc. I've also added some simplified user documentation: https://liusemweb.github.io/HeFQUIN/doc/

I've assumed that a release will look as described in https://github.com/LiUSemWeb/HeFQUIN/wiki/Release-Logistics

[hartig]

I've copied and updated the instructions from the wiki and added them to the web page. Instead of linking to the source code, the class and package references are now linked to the Javadoc.

Great. Thanks!

Yet, I understand all of these pages that have been in the wiki as documentation for contributors, not for users. Therefore, if we understand the "Docs" menu item on the Website as the entry point for the user documentation, then the links to these pages shouldn't show up there. Instead, we would need another menu item called, say, "Get Involved" (as on the Jena site) which is the entry point to the documentation pages for contributors.

I've also added some simplified user documentation: https://liusemweb.github.io/HeFQUIN/doc/

Thanks for that one as well! I haven't looked at it yet and understand that this is a first step towards a more comprehensive documentation for users (covering at least the points listed above). In this sense, we will have to think about how we are going to organize all these (user) documentation pages; in other words, we need some form of a table of contents for the user documentation.

I've assumed that a release will look as described in https://github.com/LiUSemWeb/HeFQUIN/wiki/Release-Logistics

Not sure what you wanted to say with this sentence ;-)
I understand that wiki page as another one of the pages that should be part of the contributors documentation.