Make the gh-pages home page more fast-paced and engaging

[masak]

This should probably wait until we've closed #54, but just writing it down while I have the idea.

The home page currently takes a roughly bottom-up approach to the language, going through values, expressions, variables/scoping, statement forms, subs, BEGIN/constants, macros and quasis.

But if we showed a fibonnaci implementation, we would already cover values, expressions, variables/scoping, statement forms, and subs. And if we did a format implementation, then we could at the very least cover macros and quasis. Show geht über tell.

It may or may not make sense to (quickly) build up to these two biggish examples with some slightly smaller examples.

Right now, one reason we introduce language features individually is to show what Qtree types they have. I'm thinking this could be shown side-by-side with the code snippets, as a hierarchy, much like the "Elements" tab in Chrome Developer Tools. (A first iteration can show the tree all-expanded and with no logic to collapse parts of the tree. Later we can add collapsing, and also maybe highlighting to show the corresponding text in the source code.)

One reason this would be nice is that it'd introduce the AST/DOM-like idea of Qtrees naturally, from the start, as part of real examples. Then it might be easier for the reader to accept that Qtrees are also naturally accessible from the language itself, at compile time and runtime.

In short, we can spend more time showing what makes 007 unique, and less time building up the feature set piece by piece. With the above subdivision it becomes more like a two-step process: first some regular language features, no big surprise, and then macro-related code introspection/analysis/modification stuff.

[masak]

Well, #54 is now closed, so...

[masak]

The current thinking around this issue is that the web page will have three major parts, indicated by three different background colors:

• A general introduction, where the language is shown off with actual code snippets. (Catchphrase: "007 is a language where the program structure is available for the program to inspect and modify.")
• A walk-through of the things that make 007 special, that is macros and quasi blocks.
• A reference, describing all operators, subroutines, types, methods, attributes, Qnode types, and pragmas of 007.

It just occurred to me that we should probably also develop the page so that it looks good on a mobile device.

[masak]

<masak> latest thought is that I'd like for the structure to be like this: https://lodash.com/docs/
<masak> though it'd probably be nice if above the API section, there's also an "articles" section, 
        with perldoc-like tutorials showing how to (for example) use macros, or create a custom
        operator, or inspect the Qtree
<masak> I quite like the layout of that page, too

[sergot]

I remember working on this, would be nice to come back. @masak do you maybe remember where did we stop? I see 3 branches that might be involved: htmlify, api-doc-gen, api-documentation.

What I remember is that we wanted to have this nice clickable comparison of qtree and code, thus the htmlify branch, but this sounds like a different story, maybe somehow connected later.

I believe api-documentation is the actual in-line documentation you wrote.

And api-doc-gen, is a branch I created which generates an .md file using the inline documentation, and then uses pandoc to generate the html file.

I am not sure where to start, could you help please? :)

[masak]

I agree, it's time to do this one. Here's a short inventory:

• api-documentation was indeed for writing the in-line documentation, and we finished that. That work has been merged, and is even well-tested. (Well, aside from a very minor #260.) I removed the branch from Github.
• The api-doc-gen branch looks like a good head start of having a HTML generator. We could very well rescue some work out of it, or even rebase the branch and keep going. I think there are many iterations to go before we can merge this one, but that's not because of the branch itself (which is good), it's because I have high aspirations for the resulting HTML docs.
• Similarly, htmlify looks like a good start. It strikes me that nowadays, bin/htmlify could probably be a bin/007 backend rather than its own script, but that's a minor thing. (Also, it's debatable, maybe.)

As usual, the most constrained resource is tuits. The good news is that I'm on vacation right now, and so I have some tuits to spend. I think the best concrete step I can do to get things going is to put together some HTML mockups for us to aim towards. That shouldn't be very hard, I think.

In the meantime, it might be good to know what my latest thoughts are on the subject of documentation.

• I mentioned the lodash documentation above as a possible point of inspiration. Add to that the Ember Guide, which is really worth emulating. Both of these use a navigation list to the left — I like that.
• I figure we should aim at being a bit tutorial-y in introducing the language, and doing it in "slices": when we go through if statements, we do the syntax, the semantics, and the Qtype. In the best case, that'll even provide a nice structure and ordering for the entire thing.

[masak]

For completeness I should mention that I'm currently working on writing a complete user guide in this gist.

Surprisingly, it's going well.

[masak]

We're now live with the new documentation here.

Documentation is not finished, though. Mainly the "macrology" section (which I greatly look forward to reading!) is still unwritten. Progress is being tracked in #385; I'd say when we can close that one we can also close this issue.

[masak]

I liked the look of this documentation:

It responds well to a thinner screen width, too:

I say we start from their styles and maybe adapt colors to us.

[ghost]

Also, check out the Ramda docs. A search-filter field is very simple, yet often very helpful, I think.

[ghost]

I love cheat sheets. Perhaps this is the beginner speaking, but I think that you get a good grasp on how to do stuff by use of cheat sheets. You can easily do basic assumptions and analogies in relation to things you know from other contexts. Or... another idea: a table! Perhaps compare of Perl, a C-ish language and 007/Alma. This would of course also is a short of cheat sheet, but a bit different (and more interesting) one!

[masak]

Also, check out the Ramda docs. A search-filter field is very simple, yet often very helpful, I think.

Good idea. Will think about that for the API parts of the docs. Either a filter, or at least a search field.

I love cheat sheets. Perhaps this is the beginner speaking, but I think that you get a good grasp on how to do stuff by use of cheat sheets.

It's a nice idea! Could I ask you to submit it separately, though? Exactly the same wording in a separate issue would do it. I'm eager to close this issue, and so I don't want it to scope-creep.