Fable: Build a new Fable docs site using Fable

[Zaid-Ajaj]

I thought there was a WIP on this subject. If not, I would like to build the docs site with Elmish.

Ideas

The docs site will contain documentation, how-to's for different enviroments (browser, node, react-native, etc.)

Documentation will be markdown files referenced from both the docs site (converted to html at run-time) and from the wiki

Samples:

• Independent per directory
• README.md as the docs.
• Live preview (if browser samples)
• Their code will be browsable in the browser in some sort of "directory explorer"

Suggestions are welcome :smile:

[alfonsogarciacaro]

That'd be awesome! I think @MangelMaxime is building a site for fable-elmish, we could wait until he's finished and build on that :+1:

cc @fable-compiler/documentation

[Zaid-Ajaj]

Sounds like a good idea so that we add features to one place :+1:

[tpetricek]

Let me play the role of devil's advocate here 😈 and ask: Why?

The Fable documentation is mostly just static files and using something like Jekyll to generate and host it will work perfectly fine. In fact, I think static files are actually better in many ways than dynamic content. The current generator is not quite perfect (and the way it processes samples is a bit painful), but I think that it works too (or not?)

In any case, the hard part is not how to host the docs, but to write it, so I think if anyone wants to volunteer improving the docs, then finding a couple of pain points that people struggle with and improve the documentation around that would be 1000x better than rewriting the system for hosting the documentation.

[Zaid-Ajaj]

@tpetricek I totally agree with the static files point of view, in fact, I was planning on having the docs site as static markdown files hosted on github but referenced and viewed from the site.

But I had more in mind for such website than just docs: a place where foreign developers could see Fable in action and evaluate it by playing around with a repl, previewing the samples live and browsing the code of these samples, all in one place. (Also building stuff with Fable is just fun :smile:)

finding a couple of pain points that people struggle with and improve the documentation

Already taking such approach with the docs 👍 a lot is still WIP though

The current generator is not quite perfect

I liked the idea of the generator at first, but it was restrictive on how you write the docs and mixing them with code really distracts me from reading the code itself. Could be just me though

[johlrich]

Already taking such approach with the docs 👍 a lot is still WIP though

Do we have a list yet of what people find the most challenging or specific goals for improved docs? If not, what do you guys think is the best way to produce something like that so we can start iterating on improvements

[alfonsogarciacaro]

Hi @tpetricek! First of all, I want to say the current site is great and it's one of the main reasons of Fable's popularity. You've made some valid points and I'm also always wary of making a lot of work for little improving. However, I was fascinated by the fable-arch website and I think building Fable's website in a similar fashion has several benefits (some of them already outlined by @Zaid-Ajaj):

• It's a great showcase if Fable's web itself is built with Fable and Elmish.
• Right now the way to build Fable's web is totally different from building a web with Fable (using Webpack dev server, fast hot reload...). I'm sure using a similar process would make it much easier to contribute to the web.
• The current way to have samples runnable both standalone and embedded in the website requires several tricks (special tags in the HTML and comments) that are not always easy to understand. @MangelMaxime's approach of using iframes is probably easier.
• In general, static content is fine but having some dynamic capabilities would give us more flexibility. For example, we could generate a page on the fly with the list from awesome-fable repo, instead of having to rebuild the site every time someone adds a link to it.

[MangelMaxime]

I think it's worth mentioning that using Elmish + Fable to generate/host the docs site allow us to create a DSL to help contributions.
I think this help people to contribute as they are guided by the intellisense :).

The documentation is also generated via markdown files but this happen at runtime. And as @alfonsogarciacaro said I am using iframe to host the sample which means we can host application easily as we just open a "window" to the sample web site. (This website can use any libraries without polluting the docs site scope etc.)

One last thing, worth mentioning is that we will not have the tooltip in the generate documentation as done by F# Formatting.

[tpetricek]

Hi all - thanks for the comments!

My main motivation for the comment was that static docs pages simply don't feel like a good fit for Fable. Fable is fantastic for writing complex interactive applications (among other things), but I don't see how "loading and processing Markdown on the client" would be better than doing it on the server. (In fact, doing it on the server will probably make the experience a lot simpler.)

That said, I think the idea of integrating mostly static docs with e.g. Fable-powered REPL or other components e.g. to host the samples is good - but I think it makes sense to build this as an additional JS library that is loaded from static pages.

I have seen a couple of client-only web pages that were mostly content pages and could be done as static pages and the user experience was always poorer than what static pages give you - and it is even worse when you're checking things on phone on a train or when you consider search engines.

[alfonsogarciacaro]

BTW, maybe we should start building the new website directly in a branch of https://github.com/fable-compiler/fable-compiler.github.io

[voronoipotato]

@tpetricek Honestly I think if people are willing or interested to give it a shot it might be a fun project but yeah I'd be concerned about performance as well.

[alfonsogarciacaro]

Because I like to please everybody the new Fable site is both made with Fable and static :wink: https://github.com/fable-compiler/fable-compiler.github.io/tree/dev