Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Twine Wiki needs an overhaul on the 2.0 section

edited December 2015 in Help! with 2.0
TL;DR: Let's merge twine 1.0 and 2.0 wiki into something better and more complete! What do you think of this idea?

Currently the twine 2.0 section of the wiki is woefully under-written and mostly hidden under one tiny link with the twine 1.0 stuff prominently listed as the Twine Index.

At best for Twine 2.0 you get a few vague pages and tons of random links out. It's poor wiki format to rely on links out instead of actually having the info on the wiki as it's hard to search and useless for quick reference. Most of the linked pages even use images to display code or are in video format which isn't searchable, formattable or cut and paste-able. All of this creates a very poor reference guide for Twine 2.0.

Yes, we could use plain javascript in Twine 2.0 but we shouldn't have to when the engine actually is built to handle common stuff like buttons and variables via macros. Having macros is useless if they're not written down where people can find them. Twine 2.0 formatted macros, optional extra javascript and other Twine 2.0 stuff needs to be written in the wiki where everyone can find it.

The "split version" we have right now really would be a pain to maintain as it becomes two wikis, one of which is mostly ignored and hard to find. I feel it's time to merge the two wikis into one via use of redirects and making sub-sections on main pages.

First we will have to split Twine 1.0 articles into sections per page: Twine 1.0 and Twine 2.0. Each twine 2.0 section should have sub-sections if choosing a different format makes the user require different code. Old "Twine 2.0" pages that would overlap existing pages become redirects to the closest matching page. For example the "Add Stats, RPG battles or just plain random events" page would redirect to variables as variables are used to do all of those things. The variables page would now say it's used to make "Stats, RPG battles and random events" for search reasons. The old Twine 2.0 hub would be removed/merged with the Twine 1.0 hub as it's all now one hub.

There also could be a better overall hub. The menu on the Twine 2.0 hub is nicely laid-out, even if the content isn't very useful as it stands. If the sections became more focused on grouping similar ideas with less fluff it would help people find what they need faster. For example, the "Variables" heading on the menu would have links to the main Variables page, Random variables, redirect to the Buttons page area that shows how to do variable-buttons and other related topics listed under it. Every content-bearing page on the wiki should be listed in the hub. All of them. The buttons page, for example, isn't linked from anywhere that I could find and, despite being marked as "Twine 2.0" will not work in twine 2.0 as it's all Twine 1.0 content.

Anyone else have a better option that would be easier to use? What do you think of this idea?

Example wiki page wiki code (Variables):
Rough description of what variables are and what they do taken from old Variables page. Does not include macros, just the overview part that is the same on both 1.0 and 2.0. Mention that variables are used to make Stats, RPG battles and random events for search reasons.

==Variables in Twine 1.0==
Twine 1.0 macros & code content here from old Variables page.

==Variables in Twine 2.0==
Mention general differences between Twine 1.0 and Twine 2.0 variables (if any)

===In Harlowe===
content here (macros, ect)

===In Snowman===
content here (Javascript, ect)

And yes, I tried to make a wiki account but never got a password email. Once password and general consensus has arrived, I'd love to help get this going.

Comments

  • Hi, sorry for missing your post! I think a revamp of the wiki is sorely needed, and I think integrating the documentation between versions makes a lot of sense. I think what would make sense would be to create a working area where this new documentation could be developed while the existing stuff stays in place. Does that sound like a workable approach?

    At the same time, we have to be careful -- there are no "Twine 2.0 variables" per se, just Harlowe/SugarCube/Snowman. Making that distinction is important, and a big change from Twine 1 where every story format followed basically the same syntax.

    I sent you a password reminder manually for your wiki account. Let me know if you don't get it.
  • edited December 2015
    One possible way to handle the (sometimes major) differences between how each Story Format handles/implements a set topic is to use deep hyper-links to the relevant section/page of the Story Format's own documentation within the topic's Twine 2 wiki page. This of course assumes that each of the Story Format's documentation supports deep hyper-links.
  • edited December 2015
    @Klembot It's OK. Sorry for the slow reply!

    The problem with making a workspace is that then we'd have to clean the workspace up when we're done and it might accidentally form into yet another branch of the wiki if there's more than one page of workspace. As it's really just a matter of adding new sections to existing pages and redirecting pages where needed, I don't think a workspace isn't really required. Things can always be edited or reverted as needed.

    The Twine 2.0 vs Twine 1.0 dividing lines are mostly there so there's no confusion between the versions when someone stumbles across the wiki. It also frees up the ability for the same page to be used on future versions even if Twine 3.0 has it's own versions of Snowman or Harlowe that are different from Twine 2.0's versions. It comes out much neater in the long run as then you can simply look by Twine version instead of having to read within a section and hope you are using the right version of Harlowe.

    The password arrived and my wiki account is finally set up. Hooray!

    @greyelf
    Deep links to the wiki are a double-edged sword. On one side you have fast, easy reference. On the other side, if anything should be reformatted in the future it makes all the old documentation break. Main articles don't tend to get redirected and their titles don't tend to be changed. I think it would be better to link to the main articles instead so the user can click the format/version that suits what they're using.
  • edited December 2015
    @kitsuneae
    It is true that a restructure of a Story Format's office documentation would effect the deep links in the wiki, but as a Story Format's features and office document can change on an ad-hoc basis whom do you suggest is going to keep the equivalent sections of the Twine 2 wiki up to date?

    And what would you do for concepts that are built into one Story Format but not another, for example Cached Audio, Adding Custom Macros, Event Based Javascript, Saving Story State to File, etc
  • @greyelf

    Like all documentation, the developers are supposed to keep it updated. As the documentation is done in a wiki this means that members may also add to the documentation to help keep it updated or add new ideas that work within the framework if the developer is too busy or forgets to update. As the wiki is limited as to who can edit, shows a history of former edits, bad edits can be removed/reverted, and bad users can be banned, it's pretty safe. The already existing wiki is supposed to be Twine's main documentation source anyway, not random scattered pages made by users.

    I'll just use "Variables" as an example page as it seems to be working out OK so far.

    Things that are built into one story format but not another are put into their own subsections under that story format's section under the correct version of twine and the closest matching page. For example, an inventory system done mostly via variables in Harlowe would go under "variables" then "Twine 2.0-> Harlowe". A combat system that is mostly randomization in Snowman would go under "randomization" then "Twine 2.0 -> Snowman".

    This can always be split off into extra pages if things get too huge with one page per format (ex: Twine 2.0: Sugarcube) with each page linked off the main variables page. Being able to break off pages later preserves any hardcoded links to the main variables page in a help document as the variables main page is still there and from there the user simply selects any sub-pages as needed.

    It would be OK to deep link within the wiki itself as wiki links are easily changed by users if they're outdated. This would allow a "tutorial system" of links to be developed by users if anyone wants it. However, deep links in any static form like a help file are too easy to break which is why this tutorial wouldn't be in the main help file attached to twine.
  • @kitsuneae
    The developers of each Story Format already keep their own official documentation up to date, only they would be able to say if they are also willing to upkeep the relevant sections of the Twine wiki as well.

    I believe that you are trying to combine the documentation of three distinct things into one set of documentation.

    a. The Twine application: the thing that allows an Author to edit/view different types of Passages (Text/Markup, CSS, Javascript, Image, Font, etc) and which combines those Passages to create a Story HTML file.

    b. The Story Format: the thing that defines the macro language, the core features/functionality of a story created using it and the story's default structure/look.
    Unlike the Story Formats used with Twine 1, the Twine 2 compatible ones are not based on the same core engine as each other which effects the documentation of each one.

    c. A Cookbook: a thing that contains recipes on how to implement concepts not included within the Story Format selected by the Author. The examples you gave related to Variables, Inventory and Combat are examples of different recipes.

    Microsoft tried this with their .Net library documentation of VB.net / C# / JS / ASP.net and in my personal opinion it made that documentation harder to understand because it was full of "this only works using xxxx & yyyy", "you do this differently in zzzz", "not supported by www" messages.
  • edited December 2015
    @greyelf

    Well, yes. People go to the wiki to learn how to use Twine and using twine is a combination of all three things: application, format, and macros (+ optional cookbook). Users need these three things, especially if they want to make anything more than a basic story. All three are already touched on (mostly for Twine 1.0) so this is expanding things into something useful for Twine 2.0.

    Twine itself is pretty self-explanatory and the documentation for the program itself here seems OK so far. The main format developers' documentation (or the macros at least) can be copied over here with links to the main documentation for more information. Speaking of which, where on earth are these documentation pages? Anyway, we can also expand on their basic macros with cook book stuff and comments. Cookbook stuff is optional, but I'm sure people would love to see it. We already have mostly cookbook stuff in the 2.0 section and little else.

    I actually didn't mind .Net's documentation, though it really could have been cleaned up more if things were split more into sections like I'm suggesting. It won't be a paragraph covering everything similar; It would be broken into sections so you would only be reading what works for your version of twine and your format within each section. This will help make things much, much clearer.

    So the wiki revamp will have two main Categories/sections:

    Using Twine (Stuff on Twine itself. Loading, saving, ect)
    Macros with each page broken up by Version and Format (Some redundant stuff possibly, but useful to be sure!)
    -- Cookbooks would be a sub-category of Macros if it gets big enough, but otherwise would be placed on similar-content macro pages.
Sign In or Register to comment.