Some thoughts from a new user

[Vidarls]

note: This got a bit out of hand, became badly written and a bit incohesive. Sorry about that.

TL;DR;

• Really fun approach, It suits the language very well, and looks like a really good choice for F# Api dev.
• Love the composability
• Need more / better docs and samples
• Need slightly better defaults to help me fall into the pit of success
• What about the future?

Original post:

So, I played around with Freya, and I came to think that it might be useful to give some feedback from a first-timer.

Background

I'm currently doing the first bits and pieces of an API server that will back a web applicaiton, and some third party integrators.
I did a quick and dirty NancyFX C# server to start with, but I do have a little F# crush (and a bunch of strawman arguments as to why kicking out C# is a sensible decision business-wise...)

SO: I started researching the F# web story with the following constraints:

• Need to be able to host on IIS
• Need to support owin middleware for authentication
• I need to like it

And some for the wishlist

• As little stringly typed as possible
• Need to be able to explain how to continue building on top of my first release to my team of primarily c# devs,

Jumping in

I've looked at Freya earlier, but I have to admit I did not get it at all until I watched the intro video.

After the video I was intrigued by the composability and the typed approach to http. So I decided to give it a go.

I've previously used Nancy a lot, and I'm a bit spoiled by their Super-Duper-Happy-Path (tm) philosophy. The path to Freya was not equally straight forward.

I've had one main challenge:

• Getting up and running using MSOwin security middleware

Turns out that Freya does not want to be open about her relationship with IAppBuilder. but thanks to @theimowski's music store I got it running at last.

Main obstacles have been:

**A lack of documentation and samples, or links to blog posts etc showing how other people have gotten stuff working

** A bit of a steeper slope into the pit of success**, so that people who do not read the http RFC by the bed don't make stupid mistakes.

One example here is that I was struggling with the authentication, and it turned out I had to explicitly allow the OPTIONS http method on my machine for that to work. I really never knew there was such things as an OPTIONS method.

I'm all for understanding underlaying magic and knowing how and why stuff work. I just don't think I should need know all the intricacies of the http protocol in order to deliver an authenticated JSON response from an http endpoint.

Conclusion

The web story for F# does not have a clear front-runner (except maybe Suave, but that is a complete web server, not something I can run on IIS).

I really like Freya, not the least for its composability. I fell I can create my stack for my api that I can document and pass on to my team for them to keep building on. F# and typing keeps the stringyfied stuff to a minimum, and I do have a good feeling for it.

But, But is it wise?

I tend to fall for the quirky a bit outsider girls. Some years ago it was Nancy, now it seems my heart is beeting a bit for Freya..

Nancy turned out ok for a long term relationship, but I'm slighly worried I might end up alone if I go with Freya.

(Sorry, when you all name your web fx's after women, I couldn't help my self...)

Problem is that my potential Freya project is a bit larger than my previous limited Nancy projects, it also involves more people so I'm hoping you'd care to respond to some of my concerns:

• Will Freya be around in the future?
• Can she handle production usage?

I want to see how stuff goes with me and Freya, I just don't want to feel guilty about it...

[panesofglass]

@Vidarls, thank you for the excellent feedback! I think you pretty much nailed our weak points. @kolektiv and I have talked about writing better docs and samples but keep tweaking Freya instead.

Will Freya be around in the future?

If I recall correctly, @kolektiv is building Freya as a tool to back his business. I am planning to use it in the revamped http://c4fsharp.net/. I have heard others are using it in other domains, but they must be keeping it private as no one has shared this publicly except on Slack or Twitter.

• We should do more to promote Freya's real world use!

Work continues on Freya and related parts. More and more (link to come) parts are being pulled out into useful libraries. I think Freya will be around for a long time.

• However, we really need to ramp up the contributors and/or find some backing for the project.

There's only the two of us at present, and with most of our focus on improving bits of Freya, we are creating documentation and sample churn rather than improving the quality and coverage of docs and samples. I'm hopeful that use of Freya in http://c4fsharp.net/ and the related, in-progress book will help increase that some.

If you have samples you would be willing to submit, please do! We also gladly accept PRs to the docs. I will do my best to work it into the appropriate place if you are unsure where to target the content. Just create it and send it. :)

Thanks again for trying Freya, and we hope you continue to use it. Please reach out with any questions.

Aside: I would eventually like to try to insert the security middleware into the Freya pipeline itself. If you are interested in helping, let me know.

[SimonGustavsson]

The lack of documentation is somewhat frustrating, made even worse by Freya getting tweaked and the documentation trailing behind.
So even if you do follow the docs, it doesn't work / you end up with warnings about Obsolete functions.

On the topic of usage, I am actively using it in a private project right now, if/when it goes public I'll definitely give credit to Freya, in the meantime talking to my friends about it will have to do!
As for contributing, I was contemplating helping out, at least with documentation (as it seems to be the weakest link, and my F#-fu isn't as strong as it should be, yet!). I think the thing that stopped me from doing so was the API kept changing every time I had a look / upgraded.
(How many iterations have lenses gone through now!? ;)). Not entirely sure of the procedure either if I'm honest (if there is one), just submit a PR?

Sorry for rambling, mostly just wanted to thank you both (@kolektiv @panesofglass) for your good work on Freya. Keep it up 👍

[panesofglass]

Thanks, @SimonGustavsson! Yes, procedure for updating docs is just sending a PR to https://github.com/freya-fs/freya.docs/. We can merge it into the right place (if such a thing exists). :)

[kolektiv]

Thank you to both @Vidarls and @SimonGustavsson for taking the trouble to comment, I really do genuinely appreciate that - and it's hugely helpful feedback.

I'm very happy to hear that the approach does seem to click with people (the quote "I feel I can create my stack for my api" is exactly what I was hoping to get with Freya, so that's made me smile at least). But the learning curve, and the documentation, and as you say the "pit of success" is not where I'd like it to be right now, and you're right to point that out.

In terms of the future of Freya, it won't be disappearing. Even if it had zero users, for me it's an important platform to push directions of web development and there's a lot more I'd like to do with it! So from that perspective, hopefully at least you can take some comfort that it won't vanish overnight. On the user community side though, that's going to take some effort, and I'm planning on pushing that quite a lot in the medium-term.

One of the reasons why I haven't done a bit more of that is, as you say, that at the moment the API stability is "not very stable". It's quite a new framework in some of the ways it works, and there's not a lot of state of the art in F#, so I've been inventing/experimenting with conventions as I go to some extent. I'm sorry for that, but I think it's getting there! I expect that 4.0 will likely be the last iteration of Freya with that kind of breaking API change in, as that will be the release with a more modular foundation in some places which will allow some parts of the API to stabilize while allowing experimentation in newer parts. That is in part a pre-emptive apology that there will probably be some more change coming in 3.0 and 4.0, but I'll make sure that it's accompanied by a) enough documentation and b) more sympathy and apologies. The user changes should only be namespaces and naming, and not changes to logic at least.

In terms of using Freya in production - I think it's capable. And the upcoming versions (4.0 especially which has some very solid improvements under the hood) should only make it more so. I'll also say that if anyone is running it in production and runs into a problem, I'm more than happy to help fix it - I'd like people to feel that they're not alone.

Documentation is a difficult thing, but it will improve. It's not something everyone admits, but the pace of API changes is, to some extent, what stops us doing it too... I know that's no excuse, but I'm a big believer in honesty and I think that soon we'll start seeing things settle and the documentation catch up and expand.

Thank you both again for taking the time to help with feedback. Would it be very cheeky to ask for your help? What would be good, I think, would be some prioritization around documentation. I can't expect you to write it all, but would you be able to come up with a "top 5" topics that make you tear your hair out? If I was going to document one thing next, what would you hope it was?

Also, does video content work? Particularly things like perhaps some 3 minute videos on specific subjects? Or is text best?

I'm going to stop now, before I wear my keyboard out...

[slav]

Just to pitch in on documentation, I think one thing that works very well is examples. We're all devs, so having good examples, perhaps with comments in non-intuitive places, would be great. This way as API changes things won't compile and you'll be forced to update examples. So, they'll be much easier to keep up to date.

Another thing that's good to start with is just a reference, such as a list of functions with brief description what they do. That could perhaps be generated from the code if you comment the Freya code?

I think these might make things easier to get started.

And I think videos would be great for explaining concepts.

[Vidarls]

A bit late and on my phone so this will be brief, but here are some very concrete suggestions

Roadmap

You clearly have some thoughts about where you want to take Freya, but these thoughts are not communicated. How about some high level roadmap document to let the world know your direction. Might even spark some useful discussions and feedback

Issues and ongoing work

Use the github issues for on going worm, even when it's just the two of you. It communicates that stuff is happening, it encourages community feedback, discussion and engagement. Also if you have some stuff that does not require design / architecture decisions then you could put them "up for grabs" to give users a nice gateway to contribute.

Sample repository

Seconding @slav above: Do a well commented set of samples for common use cases to show possible solutions. The music store and the todo backend is basically what got me through my startup hurdles.

Blog about it

If you've done something cool with Freya: Blog about. If you've added something new and shiny: Blog about it. Let the world know the possibilities. Also it will give google some content other than norse mythology when trying to find answers..

Code comments

Try to spend some time adding comments on the purpose of properties and functions of the public API, when would I want to use a given element?. If you do this right you can use something like fsharp.formatting to autogenerate some really useful API docs that are less tiresome to keep up to date than the docs site. The tool even support adding small samples as part of the comments I believe as well as supporting markdown for text formatting.

Not as brief as intended, but then I am a quite verbose guy.

Also not cheeky to encourage contributions, you probably should do more of that. 😊

[mexx]

Let me, as a new user, also add some words on this topic.

Production

I had a look at Freya in the very beginning of it, just a theoretical view of the concept. And already in this early stage I felt in love with it. I've tried to use it for at work, but unfortunately it was too early. It didn't support some edge case we had at the given time.

Some time has gone and now I'm developing an API gateway with Freya.
It took me a couple of hours to get a proof of concept done, hosted in IIS.
Now I'm developing the real thing for a week now and should be done in maybe a week or so.
When the implementation is completed, a production deployment will happen quite quick after.

I hope this testimonial encourage more people to use Freya, as it's definitely production ready.

Documentation

Others already stated the problems with the documentation, so I don't have to repeat it.
Just one thing, examples are really good in IMHO.

Contributing

I'll be happy to contribute in whatever area I can. As also already mentioned, a rough plan for knowing the path and some issues 'up-for-grabs' to chew on would be cool.

One more thing on this topic, please try to encourage the issue reporters to provide a PR.
Something like: "Oh, it's a cool idea, do you want to send a PR for it?" along with the pointers what to pay attention on.

[kolektiv]

Thank you all 👍

There's some great suggestions in here and i'm going to see what we can do about each of them (hopefully all should be achievable, but some might come sooner than others!). I'm going to sit down tomorrow and tidy up our issues section, and make sure that each of the things discussed here is tracked.

There's some really excellent suggestions in this thread, and I don't want to lose sight of any of it - I'll come back when I've got relevant issues/milestones tracking these things and update this thread with links.

One of the other things I'll try and get done ASAP is visibility of the roadmap/plans, etc. I hope that will be helpful and also give people some encouragement that Freya isn't going anywhere! Issues up for grabs is another great idea, and I'll see what I can do actively create some of these. I've definitely got some thoughts on that, and some amazing things which could be built which would be both examples of Freya use, and useful tools.

Finally, it's been really great to have people say they're using/liking Freya. It's an unusual project in various ways and it's always hard to know with open source whether anyone really agrees with your thinking or not! Thank you for the encouraging words, it only makes me more determined to make sure that Freya gets all of the things it needs to build a proper community around it.

[cloudRoutine]

@Vidarls, @SimonGustavsson, I think you should cut @kolektiv and @panesofglass some slack, building
and maintaining OSS projects is a largely thankless and time consuming endeavor, and this is just one
of the several projects that each of them maintains. There's a limited amount of mental bandwidth that
can be applied to adding functionality, rethinking existing code, fixing outstanding issues, don't you
want to take some of that burden off of their backs?

@vidarlis ::

One example here is that I was struggling with the authentication, and it turned out I had to
explicitly allow the OPTIONS http method on my machine for that to work. I really never knew
there was such things as an OPTIONS method.

This is the perfect example of something you could have already submitted a PR for to the documentation (and still can too! :D)
You wouldn't want other people to struggle unnecessarily now would you?

Need slightly better defaults to help me fall into the pit of success

The best way to get this started is by providing a list of specific defaults that you've already come up with.
Share with the class, we'd like to hear your thoughts ;) Concrete examples are the best way to get the ball rolling.

If you've done something cool with Freya: Blog about.

Then I assume you've already started the first draft of your own forthcoming blog post about Freya?

I want to see how stuff goes with me and Freya, I just don't want to feel guilty about it..

If you like it, then you've got to put a ring on it. That guilt you feel, that concern for the future, it's because deep down
you know you should be there by her side. Submitting PRs just to surprise and delight her, working her back up to stability
when those CI tests fail, building that new module for her that you know she's always wanted. Listen to your heart,
become a contributor.

@SimonGustavsson ::

I was contemplating helping out, at least with documentation (as it seems to be the
weakest link, and my F#-fu isn't as strong as it should be, yet!). I think the thing that
stopped me from doing so was the API kept changing every time I had a look / upgraded.

So you do understand why there aren't docs :P

Not entirely sure of the procedure either if I'm honest (if there is one), just submit a PR?

Come on now, what's the worst that could have happened if you submitted a PR just to find out? 😜

in the meantime talking to my friends about it will have to do!

Don't sell yourself short, you can definitely do a lot more than that!

@slav ::

Another thing that's good to start with is just a reference, such as a list of functions with brief
description what they do. That could perhaps be generated from the code if you comment the Freya code?

Come on guys, don't keep these lists locked away in your head. Shout it out for everyone to hear.

@mexx, @Vidarls, @slav -
Y'all say it'd be really great if there were samples, y'all have working implementations using Freya, yet there
are no PRs in sight!?! Surely you don't want @panesofglass and @kolektiv to waste their time retreading the ground
you've aldready tilled?

Be more proactive, make an effort, the more all of you do the easier it'll be for @panesofglass and @kolektiv
to take Freya further.

Ask not what the OSS project can do for you, but what can you do for the OSS project 😛

[kolektiv]

Well, we'll always welcome PRs! And of course we'll be delighted if you find a way to talk about your projects using Freya more :)

It's not always easy to get started with helping out - I think one of the big things there is making that process easier, so we'll try and make it easier for folks to find small things they can do to help out - if they feel like it! Of course, we'd always love huge chunks of work coming in, but we're not always going to get that - if the most that you've personally got bandwidth for is feedback, personally I'll always be much happier having that than not hearing it because it can't come with a PR to fix things. I know that when you're in the early stages of getting to know a system that can be pretty daunting, especially if you're not familiar enough yet to know what that system will consider "right".

So - yes we'd love contributions, large or small, but if what you feel most comfortable with is feedback - thank you, and welcome :)

[SimonGustavsson]

@cloudRoutine Don't get me wrong, I greatly appreciate the work done by @kolektiv and @panesofglass! I'm aware of the struggles of an OSS library, my comments about the documentation was made purely out of concern for the success of Freya, documentation often makes or breaks a library, and I would like to see Freya come out on top!
Judging by the great information in previous comments, most (if not all) of my concerns are being addressed / will be addressed by 3.0/4.0.

Overall some excellent feedback in this issue, I can only 👍. Public road map / plans, "up for grabs" issues, and API stability will definitely make it a lot easier to contribute going forwards!

@kolektiv

"I can't expect you to write it all, but would you be able to come up with a "top 5" topics that make you tear your hair out? If I was going to document one thing next, what would you hope it was?"

Not necessarily "tear my hair out", but off the top of my head (I haven't cross-checked everything with every page of the docs, my apologies if some of it is already covered), in random order:

1. List of APIs (Perhaps with a note about intended use?)
2. "Best practice" type of thing (you can do a lot of stuff with Freya, but should you? etc)
3. Integrating non-freya async workflows in Freya. (Freya.fromAsync? Freya.init? etc...)
4. Freya.Machine decision-graph (graphic?) with the names of the handlers/decisions in Freya
5. Update Tutorials -> Articles to use lenses. (The example looks very out of date?)
6. Some mention of how Arachne fits into the mix?
7. Custom Operators

Re .4, before Freya I'd not really come across WebMachine before, so when I did I went searching and looking at the Erlang machine. In my searches I found this https://bytebucket.org/justin/webmachine/wiki/http-headers-status-v3.png I think having something similar to that which shows which decisions/actions/handlers gets called at what point would be a huge help. Especially for people (like me) unfamiliar with the Machine way of doing things, graphics also makes it a lot easier to picture what the machine actually does (pun intended). 😄

[kolektiv]

Thanks 😄

I've created some issues if people want to track some of these things, and i'm going to be creating some more shortly as I put together what the roadmap, and try and include some of the things I know for 4.0 (and that will be quite a bit!)

For now though, here's a few top level things to keep an eye on. Where a release isn't given, read that as "hopefully soon, but not nailed down" rather than "after everything else". Some of it might well arrive sooner, but I'm not sure where I want to put it/will have resources to do it (yet).

General

• Roadmap (Public Roadmap #153) - See https://github.com/freya-fs/freya/wiki/Roadmap
• Up-For-Grabs (Up-For-Grabs #159)

Documentation

3.0

• Documentation (Update) (Update documentation for 3.0 #154)
• Documentation (Lenses Corrections) (Update documentation to be correct on lenses, etc. #162)

4.0

• Graphic documentation for Machines (Documentation/graphical inspection of Machines #161)

...

• API Comments (Code/API comments/tips #158)
• Best Practice Guides (Best-practice/when-and-where guides #160)
• Related Projects (Arachne, etc.) Overview (Documentation on Arachne, etc. #163)

Examples

3.0

• Examples (Update) (Update examples for 3.0 #155)

...

• Expanded Examples (Expanded set of Examples #156)
• Video Tutorials/Examples (Video tutorials #157)

[Vidarls]

So, this turned out to far beyond my expectations for giving my feedback after some initial framework evaluation!

Thank you to all who responded. particularly @kolektiv and @panesofglass 👍

So looks like me an Nancy will need to have a little break now, while I see where things go with me and Freya 😸

I'll make sure to pitch in where I feel I can provide any value.

[panesofglass]

As a tip to those interested in contributing with a bit more free-time and front-end experience on their hands, you might consider working on https://github.com/freya-fs/freya.ui.inspector. @kolektiv made a start, and I've been trying to carve out time to polish it up, but we have had too much other work. The general idea is to provide both a map of possible decision points and serve as a debug assistant when looking to see which decisions were made and how it progressed. Note this may experience a change with changes coming in the extraction of the Machine concept, but I think it will generally survive. :)

[kolektiv]

Absolutely on that last UI point - definitely have a chat with me if you're interested, and I can make sure you've got everything you're interested in, and also make sure you're building something that would last. And anything, no matter how small, would be cool!