Feedback required - New approach for c:geo user guide

[Lineflyer]

As I had some spare time recently and stumbled over an interesting tool ( Dokuwiki ). I started experimenting with how to easily create and maintain a user guide for c:geo.

I turned out, that IMHO the mentioned tool seems to be pretty handy for this purpose and also supports multlingual documentations (using a plugin which creates seperated namespaces with interworking).

Now I would like to get your opinion about the general approach as well as the look and feel and the style I used while creating a few example pages. I mainly started from scratch, only taking some inspiration from the old outdated manual and some parts of the FAQ.

My target would be to enhance the manual as time permits and finally (somwhen) complete the english part first (other languages can follow as soon as the corresponding english page is existing and rather complete).

For now I installed it to my private web space (and it can actually also stay there, as I have plenty of space left, unless someone has a better idea).
I created only some pages, which you will find by using the green hyperlinks from this starting point:
c:geo User Guide
Please especially take a look at the First steps with c:geo and Settings as these pages show the style I propose to use throughout the manual.

Constructive feedback is welcome, as well as help in completing the user guide in case someone has some spare time!!

Related to #84 #26 #17 (and maybe more).

[Lineflyer]

Meanwhile I added a bunch of more pages.

@mucek4
Can you change the redirect of http://manual.cgeo.org to http://cgeo.droescher.eu ?
(SSL sadly not supported)

[mucek4]

Will take a look in the afternoon. Why SSL is not supported?

[Lineflyer]

Because my webspace package does not include it.

[mucek4]

Redirect updated.

[Bananeweizen]

I'm fine with using a wiki instead of github pages. I know multiple other projects which also use different wiki implementations for maintaining some documentation or help material. When trying to judge the alternatives, this is what I would like to mention.

Wiki

• easy to contribute from outside the core team
• hard to get the structure really be the same for different languages (contributors typically don't care about multiple languages)
• hard to version, if you want documentation to fit to multiple versions of your software
• not so many tools available to integrate with the wiki content (e.g. to convert the complete wiki into a specific format needed in the software), not so easy to integrate in build scripts (if needed)
• typically the layout/style of wikis is more dated

github pages

• versioned together with everything else, therefore more easy to revert errors, and to have multiple versions if needed
• many tools available in the github universe to integrate with github pages
• easy to integrate with build process
• fresh layouts available via templates

That being said, I'm fine with switching to a wiki. However, I'm not sure if I prefer a separate wiki installation, or if we should use just another github wiki (like the one used for our development documentation).

[Lineflyer]

That being said, I'm fine with switching to a wiki. However, I'm not sure if I prefer a separate wiki installation, or if we should use just another github wiki (like the one used for our development documentation).

The main reason why I chose the dokuwiki instead of the Github wiki is, that this tools has many useful plugins available. For example with the translation/multi language plugin it should be easy to add new languages and/or translate existing pages.

Regarding the multiple version support:
I did not consider that by now, as we do not actively support older versions. So if there are changes in c:geo, we can just add/remove/modify the affected pages of the manual. No need to e.g. document outdated features. Besides that, the wiki has a version history anyway if we want to look up an old part.

Last but not least:
Maybe the github wiki offers features like the dokuwiki by adding additional available tools, however I am not capable or do not know how to integrate and configure this. So I just started with a tool, which I could easily understand and fill with data.

By the way:
The dokuwiki page is (at the moment) not an open wiki, so only registered users can modify it.
Dokuwiki provides an Oauth plugin to Github, which could be meaningful to use to give our team access to edit the Wiki.
If someone is interested to configure this plugin, your help is appreciated.

[Lineflyer]

@mucek4
I did not very often use CNAME entries up to now.
But it should be possible, that you remove the manual.cgeo.org subdomain and I add a CNAME entry for cgeo.droescher.eu using manual.cgeo.org as CNAME, shouldn't it?

Edit:
Actually I think it has to be the other way around, i.e. you setting a CNAME for manual.cgeo.org to cgeo.droescher.eu.

[mucek4]

CNAME work the other way around. I would have to set CNAME on manual.cgeo.org to "cgeo.droescher.eu". Then you would have to configure the server to accept that name. If you have such option you can try with manual entry in hosts file.

[Lineflyer]

You are right.
According to the documentation of my provider, it should accept incoming CNAME targeting a subdomain without need for action. Please just try to set it up to cgeo.droescher.eu

I assume we can't break anything as manual.cgeo.org is currently referenced nowhere and not in productive use.

[Lineflyer]

Status Update:
The manual has been finished (in english) now.

I still would love to get constructive feedback from others.
The main question would also be, if I might have forgotten an important part of the app.

While I consider it being ready for users, I would like to complete the guide in english first or correct/add items, before inviting translators. That will make the translation process more easy.

---

Regarding server things:

• After reading a bit, I meanwhile think that CNAME will not work with my hosting provider...we can still try.
• I would also offer to transfer the wiki to some other (common) server, but I also have no problem having it hosted on my personal webspace if none of you has.
• If it remains on my webspace, we could try to setup OAuth with Github as there is a plugin available for the Wiki. However I need much help for this :)
• Currently SSL is not supported in my package, I might change to another package where it is included later on. However I think having this guide without SSL is not critical...still it might be needed to implement OAuth to Github?!

[Lineflyer]

Any objection if I link the new manual on our social media page and ask for feedback by users?

[Lineflyer]

@mucek4
As CNAME will probably not work (as stated above) I would still like to solve a forwarding problem, which currently leads to malformed URLs, e.g.:

Calling http://manual.cgeo.org/en/start will reult in redirection to http://cgeo.droescher.euen/start (note the missing /) for a reason I did not yet figure out.

Can you check your redirect rule? Do you use a .htaccess for redirection or something else?

In case you use (or could use) a .htaccess file, the following should IMHO work:

RewriteEngine On
RewriteRule ^(.*)$ cgeo.droescher.eu/$1 [L,R=302]

[mucek4]

I am using apache redirection and I added "/" to redirectin and it works.
However. What do you think about this: https://manual.cgeo.org/

[niklashigi]

@mucek4 Small thing: https://manual.cgeo.org redirects to https://manual.cgeo.org//en/start (note the two slashes after org).

[mucek4]

What I did was setting https reverse proxy to lars's http server. It's the lars's server who does wrong redirect. Technically we are still sending plain text across internet, however only between my server and lars's server.

[Lineflyer]

@mucek4
I can add https to my package next month.
Regarding the reverse proxy you set up for https. Can you do the same for http? This will hide the original URL but instead show manual.cgeo.org only, which is nice.

@shroudedcode
The additional / is a glitch in the URL rewriting the dokuwiki system uses in combination with the translation plugin. Its not critical as it works nonetheless, but I opened a report at their bug tracker.

[Lineflyer]

I think this issue can be closed. The guide is considered ready to use and (as CNAME wont work in this constellation) @mucek4 set up reverse proxy to keep the URL "clean".

Now we should integrate it onto webpage and app. Will open dedicated issues for that.

I will also open a reminder issue, regarding end-to-end https support, which is currently not the case.