A static ikiwiki instance. Editing the wiki would be done via pull requests to some awesome-wiki repo and perhaps we can setup some travis-magic to auto-build the wiki (hm, perhaps we should have similar magic for the awesome-www-repo?). That's one of the less nice ways to use ikiwiki, but it would at least work.

Do we want to keep the wiki multi-language? I'm not sure how up-to-date the translations really are. Only the ru-translation seems to be semi-up-to-date. If we want to keep this:

This comment has been minimized.

A static ikiwiki instance. Editing the wiki would be done via pull requests to some awesome-wiki repo and perhaps we can setup some travis-magic to auto-build the wiki (hm, perhaps we should have similar magic for the awesome-www-repo?). That's one of the less nice ways to use ikiwiki, but it would at least work.

This comment has been minimized.

I kind of like @actionless idea. Maybe we could use a middleground here. The GitHub wiki are not very good, but there is no vendor lock-in. They are available as git repositories. Instead of PR, we could just fetch the wiki git repo when building the doc and integrate it into the main documentation. We could then build the website around that (all/most links in the mainpage end up either on github git API doc)

My migration plan from Mediawiki to $SOMETHING_ELSE would be to add a pick note at the top that we are migrating to something else and looking for help with the useful content (Mediawiki can do that, I forgot how). Then we can see if anyone actually helps. And yeah, I agree that losing most of the wiki's content wouldn't be bad.

For legacy reasons, we could get a HTML dump of the old bug database and the wiki and put it in some awesome-legacy-www repo's gh-pages branch.

This comment has been minimized.

Also note that markdown support inline HTML, so we can actually copy paste while pages and drop the table of content, then be "done". It will be fugly and uneditable, but it would show. That's a start.

Then again, there is like 15 relevant widgets pages, 10 "how to integrate awesome with software_name", the FAQ and the external module list.

This comment has been minimized.

I'm new to awesome, and I have been looking at various things on the wiki to help get me started. I have found the information to be very enjoyable and educational, so I would just like to say that this aspect (new user friendliness/accessibility) should be kept in mind for whatever the replacement might be. Us noobs need this kind of resource, readily available to non-experts, to help us out. Thanks for all the efforts on awesome!

This comment has been minimized.

@elemental7 Of course, we want to improve on this, not make it worst. What I and @actionless propose is to create a single place where you can get curated information. For now, there is the API doc (terrible in 3.5, hopefully great in 3.6), the Wiki (most content is outdated and doesn't work with Awesome major versions released during this decade) and some other places like stackoverflow and reddit.

They have the advantages of being hooked into our continuous integration and testing framework, so the examples and content (images, code, arguments names and type) are validated by a robot. This should solve the outdated examples issues we have in the wiki.

By replacing MediaWiki by a git+markdown based wiki solution, we should be able to streamline our processes into a single pipeline and generate an unified docbook.

I think most people here suggested solutions that could make this work. The big question is if we wish to have pull request for all edits. I did not use the GitHub wiki extensively, but I guess it is possible to require accounts for edits and lock some pages to user groups. This seem like enough for me. The only exceptions would be the code examples. I would still like those to have peer-review before being posted to: avoid running random code on our build system, avoid broken code and deter anti-patterns such as blocking wget/curl calls using io.popen().

This comment has been minimized.

I don't think a GitHub wiki will work out. Google suggests that spammers also attack these, so we might eventually have to lock down the GitHub wiki to only a "trusted list of editors". Meh.
On Dokuwiki: That's based on PHP. It would be nice to have some static HTML to be more hosting agnostic (and since it looks like we will use gh-pages as hosting).

This comment has been minimized.

There is also https://readthedocs.org/, widely used by many OS communities.
Compared to Github wiki, it gives some more freedom, but still not as much as a static solution like ikiwiki.
Anyway, I like it since you can browse the docs by version.
Just giving my two cents. :)

This comment has been minimized.

edited

+1 for Github wiki, -1 for some static solution that requires going through pull requests to edit. The extra hassle would absolutely prevent a lot of useful contributions.

@psychon Github wiki doesn't allow anonymous changes, it requires users to be signed up and logged into Github. I'd argue that Github's account creation system is better than MediaWiki's, so that slightly solves the bot problem. Anyway, it seems that only some really high-profile repositories suffer wiki spam, so we might as well dodge the bullet.

@alexander-yakushev Sorry, but I don't see that many useful contributions in the current wiki either. The list of user contributed themes might be nice, but just count the number of them that lead to 404s or only work in awesome 3.2 or .... As for GitHub wiki spam, the google results say that it does happen and you have zero options against it when it happens. I had enough "fun" with MediaWiki spam that this scares me.

reStructuredText: elegant and powerful markup; I find it way more convenient than Markdown when it comes to structuring data and linking to internal and external resources

Versioning the documentation along the software also eases tracking changes and keeping the pages up-to-date, plus you can set Continuous Integration builds to check the syntax of incoming Pull Requests (example) :)

edited

This comment has been minimized.

I think Elv13's plan with the wiki is "move to ldoc". However, explaining something like Vicious in the docs that come shipped with awesome feels weird since it makes Vicious kind-of-official and it means that users get the wiki from long ago. Dunno where a separate repo for "wiki ldoc" could live and I'm unsure how much of a good idea it is to write a wiki in an API documentation tool.
My suggestions would be to move that into the ikiwiki webpage since we already have that anyway for the "not wiki" part of the website.

This comment has been minimized.

independent of the underlying software i also think there might be two different solutions to distinguish between (kind of) "official" docs and "community shares".

The second one could have wiki character containing all the useful tiny code snippets, widgets, themes etc... while the official is something like luadoc which is edited by pull requests only.

Then, there should be a workflow/framework between the two repositories that merges very popular/confident content from the community repo to the official docs and ensures that there is not too much redundance between them. Also cross references should be handeled by this (to get sure to not have broken links).

Maybe i`d join the discussion to late but i also want to throw in my two bits to the "outdated" content: Even if some of the old articles are outdated they still can be useful (at least for me) e.g. to just get the idea.
I like the idea to have an "archive" of the wiki which is just a html dump of everything. It might be stimulating others to renew/improve contents from there and put them again to the new docs. This would also make the question "which articles should be abdopted?" obsolete, because its up to the community... (of course the very important/obvious articles, that would directly come into ldoc can be adopted before).
One should include a header on each page (like the actual one), with additional information (that the content might be outdated and where to find the new docs).

This comment has been minimized.

If you need a server as mirror, host or something, I'm operating a Big virtualisation host in a local datacenter. You can have a VM for free. If you need a admin I'd be glad to help.
Best regards
tdotu

This comment has been minimized.

edited

hi,
I will be glad to contribute in any kind. I have a web for Linux custom_doc and that... TerritorioLinux i can place this wiki on there, if you wish.
I'm spanish, so write on english -but idea, i guess...- But i can do someThing on translating pages . I work on md's and parse it to html after.

edited

I myself asked about a guake alternative and IRC mentioned Scratchdrop. A google search turned up awesome-scratch but it's link into the wiki is now dead. The wiki has the writeups for it and a link to the original repo. A way to go see that would be good.

There's 1395 pages in the old wiki. I'm all for moving forward and making docs good, but the wiki is worth doing some hacking on.

This comment has been minimized.

edited

The old wiki has been shut down, but can be still viewed at archive.org."

That is far from usable. There's no afaict searchability of the old wiki, and that's really bad.

From what I've heard most of it is outdated etc.

Except when it's not. And even if it's outdated, I'm in no rush to blast away all history. I appreciate that you are chiming in to recap the state of affairs (in a somewhat indirect way, but just telling me to go to the Old wiki section, as if it had a complete and working answer), and yes this information isn't all gone, but the Awesome wiki is going to be a very important archive of info for a long time, whether we like it or not and whether we do anything about it or not. I'd like for it's importance and legacy not to be frustration and aggravation for those who follows, and the partial usability of the current "Old wiki" answer will- I feel- certainly result in that. Let's get the old wiki to no longer be terrible.

It's easy to blast the wiki, with it's 'outdated' info, & had definitely grown into a beast, beyond being "merely" painful to maintain (spam). However I really really really am very sad there's not a place to spitball and put stuff on paper for Awesome. Nothing else is nearly as conversational yet captured. Reddit feels too much like writing a blurb or blog post on something, and doesn't link well at all. Stack Overflow is only for questions. I really think awesomewm should bring back a wiki. No place else let's people garden together. Even if that information is all caveat emptor, it was glorious and good and a super important vital piece of #awesomewm legacy.

This comment has been minimized.

As the current awesome site is hosted in GitHub and it's been going through a renew, I thought about creating a new section on the site to keep recipes and important stuff from awesome (configs/modules/tips and tricks), somehow like the old wiki, but way more easier to maintain (add new stuff from pull requests).

Of course a lot of things from the old wiki are still useful (xrandr script to deal with multiple monitors, for example). Any kind of help to filter important/non-important stuff from the old wiki would be appreciated.