Jamulus: Move wiki: Search engines don’t Index GitHub wiki

[ann0see]

The wiki doesn’t seem to be indexed by google:

https://github.community/t/my-github-wiki-is-not-crawl-data-by-google/947

That’s a big problem. I’d suggest a change to an other wiki app.

77 is related

[gilgongo]

I had suspected this was the case. I thought at first it was just taking the Google bot a while.

So. Github Pages? That would allow for proper internationalisation too I think.

[ann0see]

As far as I know, GitHub pages doesn't support PHP so all the translation etc. would have to be managed client side. I don't see that as practical. source forge does support PHP and MySQL but do we need to host an own wiki? Can't we use something like read the docs?

The fastest fix would be to move the wiki into a docs/folder but what about translation?

Open questions:

• What happens to llcon.sourceforge.io?
• How do we handle translations
• How do we enable contribution

https://github.com/corrados/jamulus/wiki (the base page) does get indexed

[gilgongo]

Can't we use something like read the docs?

What do you mean?

[ann0see]

Read the docs is an online documentation platform with localization:
https://readthedocs.org/

Probably there are also other services which might have some kind of GitHub synchronisation?

[gilgongo]

Probably there are also other services which might have some kind of GitHub synchronisation?

Still a bit confused. Do you mean you want something that has GitHub synchronisation but also PHP or some other server-side processing?

[ann0see]

What I‘d prefer:
A service showing the wiki hosted somewhere (not having to be maintained by anybody of the jamulus project) which displays the github wiki. So all changes would be made on github but the viewable and searchable/translated content is found on that page.

This would allow easy migration and editing by anybody (Wikipedia style). If we move to e.g. read the docs I assume we‘d loose quite some functionality (namely open editing) but we‘d have proper translation. And there wouldn‘t be an automatic github/read the docs syncronisation. But I‘m not sure about that yet.

[ann0see]

Something similar: https://www.gitbook.com/

Both seem to be quite good

Read the docs and GitHub wiki:

https://coderwall.com/p/3aamsa/sync-documentation-between-source-and-wiki-on-github

Gitbook and GitHub wiki:

https://docs.gitbook.com/integrations/github/import-of-github-wikis

[gilgongo]

Both seem to be quite good

Forgive me, but these solutions look very boring. Why not take this opportunity to present Jamulus like this, or this, or this? Something that could make it look interesting and fun rather than locking it into looking like an academic research project?

[ann0see]

Actually for a wiki it's quite difficult. I must admit that I’m not a webdesigner or similar.

What could be done:
Have two websites:
Site 1: Setup guides
Site 2: For geeks (This can be on GitHub)

By the way: I'm currently editing the getting started page. Could you please have a look at it in about 30 minutes? #602 related

[gilgongo]

OK I think it's probably a good idea to split the information architecture for Jamulus into an easily-consumable and (one day) nicely presented "front end" for normal people, then having a wiki for geeks that will I'm afraid probably become overly complicated, buggy and confusing (Just this week I had to remove to a separate page a massive amount of text about a multi-distro shell script to automate the Linux install. This was of course added by someone who thought it was OK to make it look like you have to have a doctorate in computer science to install it).

While it may be an article of faith, I do think the adoption of Jamulus is much more dependent than we realise on whether it presents itself as being hard to use. Our goal right now should be to make Jamulus usable without assuming people want to know how it works. They don't have to know unless they really want to. They just want to get it running, click on a server, play and sing.

I'll have a look at your edits with the above in mind :-)

[chrisrimple]

FWIW, I've had good success pointing people to my doc, which I've written for non-technical users. Yes, it covers more than just Jamulus, but I'd be happy to extract out portions of the Jamulus section for the Wiki, etc. I've made the same offer to the Jamulus World Jam folks.

https://docs.google.com/document/d/1smcvsxdaaViPQvGMQHmah_6BQeqowhmGSFMHfnlY2FI/

[ann0see]

Ok. So https://github.com/corrados/jamulus/issues/77#issuecomment-698497863
could be an option. But honestly I‘d just use gitbook or read the docs for the technical part at least. The getting started guides (client and server) should remain up but focused on technically savvy people. A link pointing to a site with a quick start guide has to be added there.

The quick start guide is shown on a separate page e.g. on llcon.sourceforge.io or even better (since then pull requests would be possible) on GitHub Pages. The only problem I see is translation on GitHub since it doesn’t support PHP.

[gilgongo]

The only problem I see is translation on GitHub

I was assuming that if we used GitHub pages for everything, we'd all use Jekyll, which supports i18n.

[ann0see]

Ok. If that’s the case, I‘d consider that as the solution

[gilgongo]

If we move the wiki content to Github Pages (where I assume it will be indexed), then there is also the question of how the overall information architecture should work after that. A Github Pages site would imply a fifth "home" for Jamulus: so the existing SourceForge home page, the SourceForge "site" (where binary downloads are distributed, and where the SourceForge forums are), the Facebook group, and the Github "readme" home page.

This seems to be a bit fragmented. Is that a problem?

(BTW I wonder who owns jamulus.org Creation Date: 2020-04-27?)

[ann0see]

If there's no duplicate content I'd say it's ok.

The Jamulus website (llcon.sourceforge.io) could be moved to github pages (since the devs can update it then)
GitHub should focus on everything related to coding/contributing (what the devs see).

The SourceForge site should handle downloads and the forum (what the user sees) (--> remove all source code hosted there).
Facebook (it's a private group. Therefore I don't see any issues).
jamulus.org I hope they don't setup a phishing/malware site there. That has happened to a project I followed.

[gilgongo]

I guess if we can get what's on the wiki now to appear in Google searches first then we should be OK. The problem today may be that people are finding other sources of info that might be out of date or incomplete instead.

The domain name thing is a bit of a worry (same with jamulus.com, registered in 2013). But I guess there's nothing that can be done about that really.

[ann0see]

I guess if we can get what's on the wiki now to appear in Google searches first then we should be OK.

Agree

The domain name thing is a bit of a worry

Kind of. We could of course register something like jamulus.app jamulus.music

I assume we can’t really find the owner (we can of course try via Whois)

[ann0see]

I think we all agree that the wiki should be moved to github pages. We could start a first try (with a robots.txt blocking google indexing) and we could declare the new wiki as experimental.
@corrados should create a new repo e.g. JamulusDocumentation or JamulusWiki or JamulusHelp which is a clone of the current wiki git repo. and setup GitHub pages for it. Tests can be done there

[gilgongo]

I would suggest calling the new repo JamulusHome to avoid any implication about the type of content.

[ann0see]

Yeah. That’s ok too. But keep in mind that the url would then probably be something like corrados.github.io/JamulusHome

[ann0see]

Another option would be orphan branch on the main jamulus repo named e.g. gh-pages.

https://stackoverflow.com/questions/5086833/how-to-create-a-branch-without-adding-all-the-existing-files

This would allow an url like https://corrados.github.io/jamulus

(Actually that's what I'd prefer)

[corrados]

@corrados should create a new repo e.g. JamulusDocumentation or JamulusWiki or JamulusHelp which is a clone of the current wiki git repo. and setup GitHub pages for it. Tests can be done there

You could create that repo in your account. If it is stable, I can create a fork of that in my account.

[ann0see]

Yeah. But since @gilgongo is the Wiki Manager, I‘d propose he creates the repo on his account and gives access to us.

Later, I‘d prefer to use an orphan branch on the main repo to have a central place for the wiki and the code.

PRs on this repo would then also be possible for the documentation.

[gilgongo]

OK so I've created https://github.com/gilgongo/jamulushome and made corrados and ann0see collaborators

[chrisrimple]

I'd like to contribute to the Wiki. Lots of good content in my doc that I can move over...

https://docs.google.com/document/d/1smcvsxdaaViPQvGMQHmah_6BQeqowhmGSFMHfnlY2FI/

[gilgongo]

OK @chrisrimple I added you too.

[ann0see]

Thanks!

[ann0see]

It shouldn’t be too difficult to setup Jekyll (but I have also no knowledge of it):

https://jekyllrb.com/docs/

Should the llcon.sourceforge.io homepage also be moved there (my suggestion)? This would remove one more spot where information can be found.

What about style/layout? I‘d prefer to use the same framework/colours as the website currently uses to remain consistent.

[ann0see]

I just uploaded the website.
Edit: and setup basic Jekyll templates (style, translations,...). @gilgongo should have a look at it since he should know how to handle jekyll if he also handles the wiki. I can help with setting up HTML and CSS.

[gilgongo]

OK thanks I'll see if I can get the basics of Jekyll. We also need to think about the i18n with that too I guess.

[ann0see]

also need to think about the i18n with that too I guess.

I‘ve already setup a little bit.

Edit1: There’s currently duplicate code in the index.html and wiki Layout/templates pages.

[gilgongo]

OK so I've got the repo locally (for some reason I get a permissions error when I try to clone it, so I had to get the .zip instead) and using jeckyll serve I can see it's got the home page and the gettingstarted.md

So what's next?

[ann0see]

Next steps are

• Enable GitHub Pages on your repo
• homepage translation (without breaking the structured data for SEO)
• template unification (currently the wiki has a template while the index page doesn’t have one). They should at least share the (to some extent) and footer.
• wiki navigation

[gilgongo]

Enable GitHub Pages on your repo

Done that (on /root), but: "_Your site is having problems building: The tag tf on line 1 in gettingstarted.md is not a recognized Liquid tag. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#unknown-tag-error_."

So it's not building.

[ann0see]

Probably the translation plugin is unsupported. Maybe we can change it or build on a local machine.

GitHub Actions might also be a way out.

See
https://github.com/helaili/jekyll-action

https://github.com/BryanSchuetz/jekyll-deploy-gh-pages

[ann0see]

Ok. The page is now partly working.

homepage translation (without breaking the structured data for SEO)

Done. At least the technical part

wiki navigation

Basic work is done

There is still a lot of room for improvement. I don't want to be the person responsible for the wiki ;-). Of course I can do basic HTML, CSS, Webdesign but not as the only one. Maybe somebody else also knows basic webdesign?

[gilgongo]

I've asked about the unsupported tag https://github.com/kurtsson/jekyll-multiple-languages-plugin/issues/180

Meanwhile, there is this:

http://polyglot.untra.io/

[ann0see]

Polyglot looks easier, so probably this one is better. But I don't think it's supported natively either.

[gilgongo]

Or this approach? https://www.sylvaindurand.org/making-jekyll-multilingual/

[ann0see]

Yeah, this could be a good option too. I hope it does everything needed.

[gilgongo]

My understanding of Jekyll is very limited right now, but it seems like it might be best to customise a Liquid theme that supports both i18n and GH Pages (Minimal Mistakes?) and go from there.

After all, we have some good assets already (logo, banner, colourways) and have a reasonable information architecture (although some aspects could be improved, obviously). What we lack are the more advanced aspects of front-end architecture that a theme might provide. What I don't know is the degree of limitation a theme might impose though.

[ann0see]

For me, it sounds like the theme only supports translation of UI elements, not whole .md files (in our case wiki pages). I‘d go with a custom GitHub action probably.

GitHub actions also allow HTML&CSS minification: https://github.com/nizarmah/auto-minify

[ann0see]

Ok. I've setup a branch with polyglot. For me, it's a bit messy (development) since it automatically rewrites relative links and (at least for me) does too much automatically. E.g. I had to add spaces in the translation picker which is not really dev friendly.

But there are also some pros:
It's easy to translate the title (but that's probably also possible with the other plugin)

All in all, it might be easier later for translation of single pages (since there are less folders --> the structure might be a little bit easier).

What do you think?

[gilgongo]

Not sure as for some reason I get "Could not read from remote repository" when I try to git clone (was getting that before too).

[ann0see]

That’s strange. Since you own the repo you should also be able to read it? Do you use http or ssh? I can clone it via ssh.

[gilgongo]

git clone [email protected]:gilgongo/jamulushome.git says I don't have permission.

git clone https://github.com/gilgongo/jamulushome.git lets me clone it,

Weird.

[ann0see]

Is your SSH key invalid?

But I‘m glad you "fixed" the problem.

[ann0see]

I‘ve now included the navigation.

The homepage is still missing and a link to edit the page. But all in all it can be considered as first (working) beta.

[gilgongo]

Now getting "The tag tf on line 19 in /_layouts/wiki.html is not a recognized Liquid tag." from GitHub Pages though

[ann0see]

You‘re probably not using the polyglot branch. But I doubt that this works natively either.

A GitHub action which builds the wiki automatically should be able to solve the problem and provide much more flexibility.

[ann0see]

I've now setup a github action on the polyglot branch. It does build and pushes everything on the gh-pages branch. Could you please mark the polyglot branch as default branch and setup GH-Pages on the gh-pages branch?

[gilgongo]

"The tag I18n_Headers on line 24 in _includes/headtags.html is not a recognized Liquid tag."

:-(

[ann0see]

For me, it was successful. Look at the gh-pages branch.

Edit: Now I included a German translation for the homepage as test. It does work, but I'm not yet sure how to get rid of duplicate code.

[gilgongo]

This is what I'm seeing on https://gilgongo.github.io/jamulushome - is that just me?

[ann0see]

That’s the wrong branch. You have to set the GitHub pages branch to gh-pages

[ann0see]

Currently I‘ve also blocked search engines via a robots.txt file since it shouldn’t be indexed at this stage. Of course, before publication the robots.txt must be modified

[gilgongo]

OK it's on the gh-pages branch now. https://gilgongo.github.io/jamulushome/ (on /root as opposed to /docs)

[ann0see]

There’s still something wrong. Probably with broken links. I’m going to look into it.

[ann0see]

It should - at least partly - be fixed. You need to set the gh-pages branch again (since I recreated it). I'm currently using a config parameter (baseurl: jamulushome) in the _config.yml file to prepend this automatically. Honestly, I don't think that's the correct way to do it.

It should probably not use absolute urls at all. But that's the current fix.

[gilgongo]

OK I re-set it but, 404 ... :-(

[ann0see]

Yeah. Probably there are still some broken links.

The English homepage at least works for me. (The wiki only so-so)

[ann0see]

Ok. I think the links should be fixed now (of course there can still be some I missed). It's a pain to setup jekyll in a subfolder. Probably I'm doing something completely wrong (concerning relative/absolute links).

Nevertheless, now we can import the wiki data and update the navigation in the wiki (in the _data folder)
There are still some minor tweaks necessary (e.g. how to get rid of duplicate code in index.html, how to style the language picker,...?).

[gilgongo]

Great stuff! I'll need at some point to work out how to actually edit this though :-)

[ann0see]

I‘ve added some basic descriptions (README files) which briefly describe which files are in the folders/how to translate etc. I hope, they help. You can now integrate the wiki and update the README files,...
I still have the feeling that I don‘t handle the URLs correctly but it should all work. This of course doesn’t mean it‘s handled in a clean way.

[ann0see]

@ignotus666

Can you try to translate the index.html file (homepage) to test Spanish?

[gilgongo]

@ann0see You said you added some instructions for editing. Where are these?

[ann0see]

They are in the CONTRIBUTING.md file and in the README files in every folder.

They are really basic and just describe the structure briefly

[gilgongo]

OK I'm just trying to understand all this. What is the relationship between the main branch and gh-pages?

The readme here mentions language directories, but there are none there yet, is that right?

If I were to edit, say, the Getting Started page, what is the recommended method of doing that?

[ann0see]

What is the relationship between the main branch and gh-pages?

There’s none. All the development and translating is done on the polyglot branch. The main branch is just a backup for the plug-in I initially used for translation.

If you want to e.g. edit the getting started page in English:

1. checkout the polyglot branch
2. go to /wiki/en/en-Getting-Started.md and edit it.
3. commit and push it
   —
4. The GitHub action will build and push your changes to the gh-pages branch
5. GitHub serves the gh-pages branch

[ann0see]

There are still a few todos and open questions:

• Import english and spanish wiki pages (should be done by the wiki managers @gilgongo and @ignotus666)
• Translation of website in spanish (@ignotus666)
• unify the homepage @ann0see (remove duplicate code)
• Where should the site be published? I'd either publish it on corrados.github.io/jamulus or even better on jamulus.github.io (jamulus organisation which would be great for all the stuff around jamulus like the jamulus explorer from softins) --> @corrados
• Link llcon.sourceforge.io and github wiki to the new page

Anything else I missed?

[gilgongo]

Import english and spanish wiki pages

I can do that over the next few days I hope (using the existing /wiki/en/en-Getting-Started.md as a guide). Shall I put images into /assets/img/wiki? I assume they can link using root-relative paths (<img src="/assets/img/wiki/file.png">)?

jamulus.github.io would be good!

Link llcon.sourceforge.io and github wiki to the new page

Is there anything we can do about incoming links to the existing wiki? I guess we could replace each page with a "manual" redirect...

[ann0see]

Shall I put images into /assets/img/wiki

No need for that. Github already serves them.

About the paths: that's a problem. You'd have to look into the e.g. headtags.html file (it would probably have to be done via a filter in jekyll). But honestly: just use the links which are already in there.

jamulus.github.io would be great (we'd also need to care about links then).

[gilgongo]

Github already serves them.

OK sure. And if I need to add another one I can just generate the URL for it as I've been doing on the current wiki.

(we'd also need to care about links then)

What you mean?

Also BTW I assume the user manual stays where it is for now, yes?

[ann0see]

What I mean is that if we move the site out of a subfolder to the subdomain we'd need to care about the links since the baseurl would need to be changed along with a few bad hacks in the Code. But that's actually good.

I don't know about the manual though.

Why is it even in the normal repo?

[ann0see]

I have now unified the homepage. Not all html is gone now but I think we can't remove everything. The main visible content (excluding the header) is still in the html files.

Is there anything we can do about incoming links to the existing wiki? I guess we could replace each page with a "manual" redirect...

Yeah. That's probably the only option.

[gilgongo]

Why is it even in the normal repo?

I think @corrados gave me a reason a while ago but I can't remember what it was.

[corrados]

The manual basically contains the same text as the tool tips which are compiled into the Jamulus software. So the idea was to keep these in the same repo. But if there are multiple reasons to change this and put that file to a different place, we could do that. I'm fine with that.

[ann0see]

Maybe we should keep the manual (English only) and add a separate, more practically focused description in the Wiki (since in my opinion a user should want to just follow instructions how to get started as fast as possible. He doesn't want to read the whole manual (yet))

This wiki page would show

• How to set a Name (Step by step)
• Where to find the settings (Step by step)
• How to connect to a server (Step by step)

Afterwards a "more information can be found in the English Jamulus manual" statement.

[gilgongo]

I guess it may not hurt to have a brief description of those things, but I'm always a bit wary of making it look as though Jamulus is harder to use than it really is perhaps.

Meanwhile, I've imported all the existing Wiki files now in the en folder. There are a couple we can leave behind I think.

There are some CSS tweaks we could make I think, and we need to get the navigation hooked up. How's that done?

[gilgongo]

BTW why do we have this page? https://gilgongo.github.io/jamulushome/wiki/

Can it just be this one? https://gilgongo.github.io/jamulushome/ Having two "home" pages feels a bit confusing.

[ann0see]

Meanwhile, I've imported all the existing Wiki files now in the en folder.

Yeah, I've seen that.
The CSS has to be done. It looks quite stuffed at the moment.

BTW why do we have this page? https://gilgongo.github.io/jamulushome/wiki/

This was basically https://github.com/corrados/jamulus/wiki
Yes, two homepages might be confusing. But we should have a page which talks about contribution, which pages might exist (but the user doesn't need to read on first setup, like the sever setup,...)

The navigation can be edited in the _data/en/wiki/navigation.yml

[gilgongo]

_data/en/wiki/navigation.yml doesn't seem to like being.... oh. It's yml :-( What are the rules for the indentation?

[ann0see]

I used the official Jekyll documentation and extended it a bit:

https://jekyllrb.com/tutorials/navigation/

Especially have a look at Scenario 4

[gilgongo]

OK done that. Can we have the logo in the header link to /jamulushome/ and not /jamulushome/wiki?

[ann0see]

Yes, we could. But I'm not sure if that's really what we want. I think the wiki should be separate to the homepage in my opinion. A user probably wouldn't like to get back to the landing page (which doesn't really help since there's no navigation, the layout is different,...). By the way: a index.md file in the Wiki must exist. I'd make it a collection of links.

My way of thinking about the structure is that you have a Jamulus homepage (without subpages) and a jamulus wiki (with subpages).

This would allow us to separate and simplify the wiki structure.

There would be a fast setup guide mainly for clients and a separate branch for the server setup.

[gilgongo]

We appear to be increasing the number of "home pages" in that case. What is the utility of a "landing page" if it's separate from an "index page"? As it is, we have the following "top level" pages, all apparently "home pages" in some way:

https://sourceforge.net/projects/llcon/
https://gilgongo.github.io/jamulushome/
https://gilgongo.github.io/jamulushome/wiki/
https://github.com/corrados/jamulus/

We can't do anything about https://sourceforge.net/projects/llcon/ really, since Volker is for good reason committed to SF. And we have to have https://github.com/corrados/jamulus/ in common with other open source projects.

But can't we combine https://gilgongo.github.io/jamulushome/ and https://gilgongo.github.io/jamulushome/wiki? Having a "collection of links" feels redundant. I'm unsure how having them separate "simplifies the wiki structure" by having two home pages on the nav - we don't have any other content that's not the wiki or the user manual in any case.

[ann0see]

Ok let me explain:

llcon.sourceforge.io (current homepage): Landing page will be moved to jamulus.github.io (hopefully). No problem
jamulus.github.io (new homepage): Wants to get more traffic to the Jamulus project. Is an introduction lays out what Jamulus does,... A user should only see this page once.

jamulus.github.io/wiki (the wiki). The Jamulus wiki is a general knowledge base of Jamulus. Not only a getting started page. Currently it is mostly focused on how to get started but also contains other important information a user might not need for the first setup but maybe later. He doesn't want to click through various getting started pages to somehow find compilation instructions for a headless server. But the average user doesn't need this information. Therefore the "collection of links" is needed. It simplifies the structure because it allows us to link the Getting Started page with only information needed for the first setup and we could also link a few sites for more advanced setups like setting up a server/cli/compilation/...

It doesn't make sense to link the user back to jamulus.github.io because the intention behind the wiki is that he finds information on how to configure/setup Jamulus not that he gets persuaded to download it (since he will do it anyway).

https://github.com/corrados/jamulus: The source code. Everybody except the developers doesn't even need to know about this.

https://sourceforge.net/projects/llcon (in my opinion we should focus on a discussion forum here only). This is mainly used for getting help not covered in the wiki.

[gilgongo]

"A user should only see this page once." Why is that? The convention of "splash pages" for sites no longer exists, surely? I didn't realise we were expecting the home page not to have the navigation to the rest of the site. That's very unusual, isn't it? Do you mean we should have a site map that links to every page? We could, but that's not something expected at the top level of a site. Something for the footer perhaps?

[ann0see]

I didn't realise we were expecting the home page not to have the navigation to the rest of the site.

At least currently it doesn't. For me the wiki and the homepage have totally different intentions and therefore mixing them doesn't make sense but we can of course try to find a compromise.

Do you mean we should have a site map that links to every page?

Site maps at least for google would be good, but not for the user. Who looks at sitemaps nowadays?

The index.md file in the wiki would state something like:

Welcome to the Jamulus wiki. Here you will find information about setting up Jamulus (link to getting started page), Configuring a server and more advanced options to setup Jamulus. If you need help, feel free to ask on the SourceForge forums.

Contribute
...

A normal user wouldn't even know this site exists unless he clicks on the Jamulus icon on a wiki page.

[gilgongo]

I guess where we disagree is in your statement that the wiki and the homepage have totally different intentions.

The intention of the home page is to be the "top level" or "home" for Jamulus (ignoring for the moment SF and GH). If we had a domain name like jamulus.com, it would serve that page from the root. The universal convention of such a page is that the navigation to the rest of the site's content also appears there in some form. You would not need to go to a different place to discover that content existed, and any link called "home" would also go to the home page.

And I don't see a distinction between "the wiki" and the rest of the site, since the content in the wiki is the only content we have. In fact I'd prefer that we didn't talk about a wiki and encouraging contribution at all really, since that implies we want an ever-growing stack of information. I don't think that's a good idea, because we're approaching too much documentation as it is, let alone the burden that a wiki model imposes on the translators.

If we must live with this separation between "the wiki" and "the home page", then at the very least we should put the site navigation in some form on the home page. Why would we want to hide it? And if we must have a link to an index of "the wiki" then let that be the "Contribution" link (although I have to say I do oppose that, as I know @ignotus666 does as well).

[ann0see]

Yeah, that's probably what we disagree with. I think the main question is: What is the wiki for?

Getting started guide with basic information (only for less experienced end users. This would mean that even compilation, CLI,... should be hidden or even not documented in the wiki) or

a full documentation for Jamulus (this would include compilation, tips and tricks, technical descriptions (like client-server principle, how to setup streaming,...)). I think we should maybe divide it more clearly into an easy and more advanced section.

[gilgongo]

divide it more clearly into an easy and more advanced section.

Making an explicit divide in site navigation between something like "easy and "advanced" usually encounters three issues:

1. Where you draw the line (because one person's "easy" is another's "advanced" and vice versa, should you have a "super advanced" and so on)
2. Lack of orientation cues (because people note links to things without clicking on them: "orientating")
3. Duplication of information (although mainly an issue only if we encourage free contributions)

BTW I'd not make the first issue worse worse by making people understand that when we say "the wiki" we mean "advanced section". But I take it that's not what you mean and that you simply want a hard divide in the navigation between "easy" and "advanced".

The structure of the docs right now is supposed to allow people to "flow" though the information and stop once they feel they have enough. Some will look at the "Getting started", install and configure without further interaction (or may, having orientated, come back later for more). Others may also want to read up on Hardware Setup and perhaps Configuration before they feel confident to start jamming. My point is that we don't know what they need, but they should be able to do what they need without having to stop and re-orientate. We just need to ensure that the IA flows naturally from high to low-level information.

This isn't to say that the flow can't be improved, but I think the above can be achieved by incorporating the navigation into the home page and removing the distinction between "the wiki" and "not the wiki".

[ann0see]

I agree that the wiki is a bit messy. We can add a navigation in the homepage. Which site should open if a user types jamulus.github.io/wiki? Should the getting started page show up? I assume so.

[gilgongo]

In so far as that's the start of the documentation, then I think that would make sense.

[ann0see]

I'm not sure how to do the redirect.

My suggestion would be to not link the this page but make it an automatic index to all sites available (like the current "sites" button in the wiki) if someone wants to access a specific site we don't link in the navigation, this could be some kind of advanced entry point.

I've restructured quite a bit at the moment. The navigation is now shown on the main page. It looks a bit different; I'm not sure how to improve the design.

[gilgongo]

OK that's working I think. Not sure what you mean by "an automatic index to all sites available" though. What's a "site" in this context? Is there a "sites" button on the wiki?

BTW now that we know we can't publish on jamulus.github.io, I guess we'll have to put it on corrados.github.io/jamulus.

EDIT: In a moment of total madness, I just registered jamulus.io. Not sure if that was a good decision, but it was only $19.

[ann0see]

an automatic index to all sites available
Is there a "sites" button on the wiki?

It's something like that but it's only shown if somebody types jamulus.github.io/wiki

In a moment of total madness, I just registered jamulus.io

I'd first wait since I still have something.
There are probably cheaper hosts (see netcup.net).
Check your e-mail (from github). Please don't discuss it online, but it might be a way out.

[ann0see]

I've hacked it together. Now we must wait how we continue (either with jamulus.io, jamulus.github.io or my solution). Of course jamulus.io is maybe better but @gilgongo must pay for it yearly/monthly.

647 but asking for donations or paying in general could potentially move the project to a wrong direction.

[chrisrimple]

If funds are needed for Jamulus, I'm sure that the Jamulus WorldJam community would contribute. As an alternative to crowdfunding, what about Jamulus-logo clothing, sold as a fundraiser? The WorldJam has recently begun offering logo clothing, which is very popular, but is sold "at cost" (by the printer) so no funds going to the WJ - the Jamulus project could do the same but maybe add $5 USD or similar to the item cost, with the extra going to the project.

[ann0see]

It's not the best domain, but you can now see it here: https://jamulussoftware.github.io/

[ann0see]

@gilgongo It seems to work now. I had to add a CNAME file to the repo. It didn't do that automatically. Could you please also add a CNAME entry for www so that www.jamulus.io also redirects to the correct server?

[ann0see]

The last steps are:

• Check that all links work (since some wiki pages are missing) (hopefully done for now)
• Setup www.jamulus.io redirect (done)
• Include the new domain in the next jamulus version (todo)
• Setup redirects (moved permanently) on llcon.sourceforge.io (todo)
• Check that everything works (todo)
• remove the robots.txt file which blocks google to index jamulus.io (todo)

[gilgongo]

Also make the current GH wiki read only prior to (presumably) replacing all pages with links to their corresponding pages on the new site?

[ann0see]

Yes.

[ann0see]

The todos can now be found here: https://github.com/jamulussoftware/jamulussoftware.github.io/projects/1

I will close this issue since I think we should continue discussion on this repo: https://github.com/jamulussoftware/jamulussoftware.github.io