Tutorial 1 notes

These relate to the README, introduction, background, and Make It Markdown Tutorial 1

My index is here (that's the direct github link)

• or with the double-square-bracket link straight to the flowershow version: README

Note that the double-square-bracket link works in Flowershow, but not in the native GitHub text. I'd say that is an unfortunately confusing problem, and a serious compromise of usability.

I've noticed the PortalJS tutorial and I'm wondering how much has just been lifted from there. It's actually quite different in content. What they have done well is to put partial screenshots everywhere so that you aren't hunting round looking for the thing you're trying to find. It does however explain the rather mysterious README page for the guide where it says “Tutorial 1: Create a website from scratch using markdown and PortalJS” when we are actually talking Flowershow as the thing us learners are interacting with.

The Introduction has a table of contents — not sure whether this is really needed, but it could be helpful if you're trying to get back to where you left off.

The Background and motivation page has some unexpected back-ticks around “# This is a Heading” and “This text is bold”. The rest of this page is generally helpful. At the end of the page, the link to Next has no space underneath. Some space might help the link to be easily seen.

So, on to Tutorial 1 itself. Near the top it says

Below is a screenshot of how the final website will look like:

I'd say this is a little misleading, as what the final site looks like will depend on what is entered, and the instructions don't explicitly tell you to enter that (complete with some “Lorem ipsum” text). How about saying that it will depend on what you enter?

I managed the “Setting up a website” part fine. It's quite involved, but manageable. Likewise with the “Editing a page on your website”. The wording of “Commit” is very unfamiliar to non-coders, and could be felt as pretty offputting, as all other common editing systems work with “Save”. So worth more of a long explanation of that, inline.

Now is where I came unstuck, on “Add a single Markdown-based page”. First to note is that, sure, if your window is wide enough, it shows “Add file”, but if your window is too narrow, that changes to a simple "+". Worth a screenshot of both here.

Then, sure, it says “At the end of your file name, make sure to add '.md'. For example, 'about.md'.” But I omitted to put in the .md, and that causes all kinds of problems. So worth making that much larger, as part of the heading, not just in ordinary text. Also it is essential to write something before you commit, I discovered, as if you don't put in any content it seems to make editing it later impossible! So, make that point under the point 4.

Point 6 could do with an illustration, to be clearer. Same point as above, about the space under the Next link.

On to tutorial-2 (with double-square-brackets)

end