I've been working on a guide to writing stories using the Harlowe format and have decided to release a first version.
http://twine.analytical-engine.co.uk/index.html
Notes: The guide was created using Twine.
It only covers the basics at the moment. I'm planning on adding more complicated stuff.
I'm also planning to add a cookbook to show how to solve common problems.
If anyone has any comments, corrections or suggestions then let me know.
Comments
Other than minor typos (which I'd be glad to point out), the beginning threw me a little bit.
It says:
"This is a site about creating interactive fiction using the Twine 2 program.
"This guide soley uses the Harlowe story format, though there are others available. A list of formats is here" (with a link to "here.") (note: "solely" spelling.)
Then on the next page it says:
"Harlowe
The default format and the one that this tutorial uses. The manual is here." (with a link to "here.")
I felt that it was disconcerting to be taken right out of your Guide on the second link to the official documentation. At first I thought that was the extent of your Guide! Then, going back to your site, I noticed the link to your Guide in the header, and I was good to go from that point.
In other words, I feel the natural flow of your links takes you out of your own Guide, which you probably don't want, and that the link to your Guide is not prominent in the header (fifth in line). Maybe I'd link the word "Guide" and capitalize it in "This guide solely uses…."
That's what I noticed right off the bat. Otherwise, excellent effort!
Anyway, this guide is amazing and much needed.
It would be great if you could also add more examples that users can try in their stories.
EDIT: for example, a more detailed description of how to use the special passages, and anything about how to create passages that execute stuff (which makes it easier to work with variables).
I'm going to keep working on the guide. Writing it is a good way to learn all the different features.
Could you explain what you mean by this, or are you talking about the Story Javascript editor?
I mean exacyly those three.
The guide currently has a paragraph that says:
I think it would be useful for Twine / Harlowe users to expand that subject with some practical examples of how these work.
The current description tells exactly what the passages do, but there are many things one can achieve playing with those passages, I think examples would give a clearer idea of the possibilities.
I was thinking, as an example, to passages an author may want or need to create specifically to make sure that certain variables or macros work as intended.
Sure, you can always set your variables directly in a specific passage (or in your startup passage), but you may want to have some logic or other kind of "background" operation in a separate passage.
The available documentation seems to mostly cover basic usage of the Twine 2.0 / Harlowe functionalities. I think it would be nice if the guide could expand the subjects a little bit.
Of course, users can always try things out, get creative, or look at the forum, but I do think that there is a bit of a gap in the documentation that this guide could fill.
Sorry, I am still new to Twine so I don't think I have all the terminology right, hopefully I sound less like a very confused pidgeon now...
Some of the cookbook examples make use of headers and footers, but I'm also going to improve the description in the special passages section.
On a side note, I've added an auto generated index page. Which is neat.
The main changes are:
Following suggestions here I've added links to the guide to the front page, and made external links more obvious.
The parts about using the twine editor have been moved to a separate section.
I've added an index
I've added some macros which had been missing
I've added a cookbook
It's now possible to view the source code for any page (Including headers and footers)
It's now possible to link to a particular passage: http://twine.analytical-engine.co.uk/index.html?p=guide will go straight to the harlowe guide
There's a link which gives the url for each passage
I've added a sandbox will lets you try out Harlowe macros.
If you spot any errors or typos or have any suggestions, then please let me know.
I was away so I only had time now to play with the new guide.
Awesome job!
I found a small issue in the cookbook/inventory: when I click on "Play example game", I get:
EDIT: I hadn't yet tried all pages when I wrote this comment, but it appears that this happens with all of the examples in the cookbook.
(I just tried the countdown one).
I'm thinking the best thing would be to deprecate the guide and focus on things like the cookbook and example games.
If anyone disagrees with this then let me know.
I love your guide and have used it a lot so far, but with the new guide being live, a cookbook and example games would be most useful.
It's been tested on Firefox and Chromium, and seems to be working okay. However I don't want to replace the old cookbook till it's been tested a bit more thoroughly. If anyone wants to try it out then it's at http://twine.analytical-engine.co.uk/Cookbook_test.html
There are a couple of issues with Chromium:
While the cookbook works online, if you download it and try to run it as a local file it fails. This is due to Chromium (and presumably Chrome) blocking the history api for local files. I plan to detect if the history api isn't working and going back to the old way of working in that case.
If you do the following
Go to the cookbook from another site
go to one of the first pages
click back twice to go back to the other site
click forwards twice
It produces a javascript error which breaks the cookbook. I'm not sure what's causing this to happen, especially since it doesn't happen on Firefox.
Minor issue - there is a spelling mistake in the cookbook's first page (http://twine.analytical-engine.co.uk/Cookbook_test.html?p=start). Should be Miscellaneous.
Weird issue - this is somewhat similar to what you described in your post, but it happens to me on Firefox:
1. go to Styling
2. click "Adding a picture in a box"
3. click "Play example game"
4. hit the browser's back button twice
5. the following error is displayed: 6. Nothing happens until the page is reloaded.
This happened to me 3 times out of the 5 I tried to repro the issue.
I didn't try with any other link, but let me know if I should.
Edit:
Just noticed another typo in the cycling link page of the cookbook.
"Neutral" is spelled "Nuetral" throughout the page.
When moving to a new page Firefox is supposed to keep a record of the whole state of the previous page (including any javascript) in a special cache called the bfcache. Chrome doesn't do this at all and it seems that Firefox doesn't always do it properly.
This means that after moving to a different page and back again, the engine will have lost its list of visited passages, so any attempt to move between passages will cause the error that you're getting.
Thinking about it a bit more it's pretty clear that when I was working on this I had a bad case of Jurassic Park syndrome. I was so busy thinking about what could be done, that I didn't stop to consider whether it should be done.
Given the number of problems that interacting with the browser history causes (some which only happen intermittently or on certain browsers) I'd have to spend a lot of time keeping the site working, which would be better spend on improving the examples. So I'm going to abandon all the browser history code.
Thanks for testing it.
I found an issue in the savee/load example of the coookbook.
For the "loading when a player specified the name", you have the following example:
I believe one [ is missing, so: