Consider the future of the Wiki

Create issue
Issue #24 resolved
David Williams created an issue

As discussed here: http://www.volumesoffun.com/phpBB3/viewtopic.php?f=2&t=463

It seems one option is to investigate the BitBucket Wiki and move the content across. Probably we should do this before the 0.3 release.

Comments (19)

  1. Jesse Johnson

    Would you mind if I go ahead and do the port to BitBucket? I am currently writing an updated Ogre-PolyVox integration tutorial for PolyVox 0.3 and Ogre 1.9 and would prefer to only have to write the formatting once.

  2. Matt Williams

    Looks good. I would suggest that we use the reStructuredText markup option as that is the same as we use inside our official manual. It doesn't seem possible to select this as a wiki-wide option but we'll just have to make sure it's set on each page for consistency.

  3. David Williams reporter

    I wrote that in a hurry as I left work without looking at the Wiki options properly. I assumed we had to choose a markup mode for the whole Wiki, but as you say it actually it looks like it's a per-page option. I suggest we use reStructuredText for any pages we create but that we let contributors just use whatever markup they are most comfortable with.

    We should also take responsibility for an index page, some introductory text, and for pulling some content across from the old Wiki if relevant. I'll leave this task open until that is done.

  4. Jesse Johnson

    Do you guys know how to quickly add wiki links in reStructuredText? I could not find anything on the syntax in BitBucket documentation. The format seems to be:

    `Article <article_name>`_ 
    

    That is rather long and difficult to type for a wikilink. I love reStructuredText for documentation, and was initially excited to try it out on a wiki, but after seeing this I am nonplussed.

    Creole is a sort of internationally standardized amalgamation of MediaWiki markup and the other popular wikis with the intention of promoting consistency among wikis. It may be a better choice for a default markup in a wiki. It uses the simple wikilink style of MediaWiki and most others. What do you think?

  5. David Williams reporter

    Yep, like I said in my previous comment I actually thought we had to choose a single markup format for the whole Wiki, but this doesn't appear to be the case. We want to make contributing as easy as possible so I think we should let people use whatever markup they prefer for the pages they create (you can select your chosen format from a dropdown box). I admit the reStructuredText link syntax has baffled me in the past :-)

    This does mean we may end up with a mix of markup fomats being used in the Wiki which might make editing other peoples pages slightly more tricky, but these are likely to be small edits anyway so I don't think it's a big deal.

    So yeah, I think you should just use which ever format you prefer and we'll just use reStructuredText for any of our own pages.

  6. David Williams reporter

    I'm having second thoughts about mixing multiple wiki markup types. I know very little about Wikis but it seems this might start to cause problems with cross referencing between pages? I.e. if a label is defined in the middle of one document then maybe it is hard to reference it from another document if a different markup is used?

    Having now flicked through the BitBucket documentation I get the impression that Creole is a bit better supported... at least BitBucket make some special references to it here: https://confluence.atlassian.com/display/BITBUCKET/Special+Support+for+Creole

    So maybe we go for Creole instead? I don't have any real preferences but we want to avoid people having to redo their work. Sorry to be all over the place with this, but I just don't have the experience to make informed decisions!

  7. Jesse Johnson

    No problem! Better to think it through now than regret it later. =) I edit Wikipedia and Wikia almost daily, so I was thinking the same thing you are now: multiple markups will make collaborative editing a headache, somewhat defeating the purpose of a wiki.

    I would suggest Creole as the alternative to reStructuredText if only because it is similar to MediaWiki and thus familiar to most people who edit wikis. Sort of an establihed common tongue, hence its name. Plus, as you mentioned, apparently BitBucket seems to provide better documentation for Creole.

    I won't start writing my article until a decision is reached, so no rush. I still need to strip my example code of profanities and kludges anyways. =)

  8. David Williams reporter

    Ok, I've given it some thought and decided... it really doesn't matter :-)

    ReStructuredText is nice for consistency with our user manual, but I doubt if Matt and I will do much editing of the wiki beyond creating the index page (at least we haven't in the past). Markdown appears to be used by BitBucket in other places such as this comment thread. And Creole has some advantages as mentioned above.

    I'm more or less flipping a coin here but let's go for Creole.

  9. David Williams reporter

    Also, I'll be away for a few days so if there are any issues (admin permissions, etc) then I'll sort that out when I'm back. Matt can probably also do it, and I might even have internet access but I'm not sure.

  10. Jesse Johnson

    I completely forgot about licensing for the wiki. While CC BY-SA licenses are fine for text and images, they are not compatible with the GPL and therefore should not be used for source code. I suggest the CC0 license, which provides a means to make your code public domain or its closest equivalent depending on the locale. It is better than simply releasing something to the public domain because not all regions have such a legal concept and therefore your work could be construed as not being freely available in those areas.

  11. David Williams reporter

    I hadn't thought about licensing but I would indeed be in favour of using CC0 or some other public domain type license. There's also http://unlicense.org/ but I think the Creative Commons licenses have wider recognition.

  12. Matt Williams

    The license of the text of the documentation shouldn't matter too much but there would indeed potentially be a problem with any source code examples. PolyVox itself is zlib licensed which is compatible with almost everything so explicitly saying that all source code in the wiki is zlib too would be viable.

    On the other hand, I'm fine with marking it all CC0 to make it as widely available as possible as long as it's valid in enough jurisdictions.

    Of course, by marking it as CC0 we'll have to ensure that anything we add is our original work or uncopyrightable but that shouldn't be a problem for the contents of the wiki.

  13. David Williams reporter

    I do find attribution clauses to be troubling in licenses because it's never clear to me how far they extend. If Person A creates some work and then person B uses it and gives credit to person A then that's fine, but if person C then uses the work from person B then do they also have to credit person A? There's probably is a proper answer to this but it's not immediately obvious to me (so I'm guessing it's not obvious to users either).

    Matt makes a valid point that we might not have the option of making everything CC0 (depending on it's source). I think we should say that content of the Wiki is assumed to be CC0 unless specifically stated, so that contributors have the open of marking particular source snippets as a different license.

  14. David Williams reporter

    Ok, I've just ported (almost) all of the old Wiki content to the new Wiki, written some Wiki guidelines, and created the main index page. I think it's over to the community now :-)

    I'll also fully close down the old Wiki and then close this issue. I think we can move discussion about the Wiki back to the forum now.

  15. David Williams reporter

    This issue can be closed now. The old wiki still technically exists (see here for example) but all pages just point the reader to the new wiki.

  16. Log in to comment