Documentation needed
isaacabraham opened this issue · 14 comments
We really need to put some decent documentation on the site here. It shouldn't explain all the details of Fable / Azure / Elmish / Suave / Saturn / Giraffe etc. - that's the job of those repos etc. - we should have content that shows how to tie them together, how to get started etc. etc..
@Krzysztof-Cieslak is it possible for you (or anyone else - I have no clue how Jekyll works) to create a basic TOC page for documentation and then point me / @bruinbrown / @theprash in the direction of how to create a new page and link to the TOC? I'm happy for us to add to it over time - we just need the basics in place.
- Introduction
- Why SAFE?
- Getting up and running
- Quick start
- SAFE Dojo
- Example repositories
- Feedback & Testimonials
- Support and Training
- SAFE Stack overview
- Server Side programming in SAFE
- Suave
- Giraffe + Saturn
- Cloud Platform - Azure (AWS + GCP to come?)
- Client Side programming in SAFE
- Fable
- Elmish
- Server Side programming in SAFE
- Mobile SAFE
@isaacabraham it would be good to make something in line with awesome-list ? or you are having something else in mind ?
What's that? All I think we need is some way of people being able to add new content easily and quickly.
I'll do that - just one question. I've been using for my documentation pages (http://ionide.io/docs/, https://saturnframework.github.io/docs/) mkdocs (http://www.mkdocs.org/) instead of Jekyll. The big difference is that mkdocs is (as name suggested) focused mainly on generating documentation, and works better in this scenario than Jekyll from my experience. The only problem is that it's Python tool, would that work for you?
@isaacabraham something like this https://github.com/kunjee17/awesome-fable . It is not documentation for sure but it is definitely collection of things done by people / group.
Yes, this is great. So there's lot of overlap here - my preference would be to incorporate a lot of this into SAFE documentation as the "goto" place for that, but open to ideas.
@Krzysztof-Cieslak I don't mind either way. Jekyll needs Ruby anyway so I'm not bothered- basically whatever you think is thing to be easiest to use :)
@isaacabraham awesome list can start right away. I did put starting links and all other is from community. You just new 3 md files. And then it can be added to safe documentation.
What I feel is documentation is more of little dense. So, normally it do took time. I did like recent approach of MSFT for their new docs site. Again it is all question of preference what we like to have first and how we like to have it.
@kunjee17 detailed docs for Suave, Giraffe, Saturn and Fable etc. all stay on their own sites I think. The objective of the documentation on SAFE is to provide some place that we can join the dots together - somewhere where the individual sites may not be suitable for, such as how to start, why, when to use what etc. etc.. Alternatively, it could be for issues that cut across all the products. An example of this could be the recent one on client / server JSON communication.
If someone hears about SAFE, they should be able to go to this site and read up on what it is, how the different components fit together etc. etc., and then have resources from where to learn more about the individual components.
@isaacabraham ohk... In that case documentation would be better approach.
@kunjee17 see the checklist in the main issue - that's the sort of thing I want to have.
@isaacabraham we can do one thing... Short term we can start with awesome list, preferably safe-stack organization only. It will allowed users of Safe-stack to contribute with links to their work.
And then we can try to stretch goal of proper documentation. @Krzysztof-Cieslak and @MangelMaxime would be way better to guide in that direction. I am using Fulma, and it's documentation (also way of creating and dogfooding it) is quite a great example. Very much happy to help there...
PS: As I mentioned earlier, I just created skeleton and then community added stuff. So, currently maintaining awesome-list is like accepting PR, and fixing duplicate link errors only...
Repo for the documentation - https://github.com/SAFE-Stack/docs
Online docs - https://safe-stack.github.io/docs/
@Krzysztof-Cieslak thanks so much for doing that. I've now managed to get it running locally and started putting in some basic content here. I'll have something ready later this week for review.
I'll also migrate the task list at the top into that repo and close this issue tomorrow.