Add README.md file to SAFE Template content #183
Conversation
|
@WalternativE first thanks for this :-) I've no objection to this at all in principle. The only question I have is around duplication of text - we have the quick start here and could link to that instead? Alternatively, perhaps we could include the file from that repository as a paket dependency into this repo and rename it as readme.md? Thoughts? |
|
So, I don’t think we should only link to the webpage, having some readme in generated project seems like an good thing. Coping file may be good idea, on the other hand it seeems like the type of design where you try so hard to abstract over something to not repeat any code that you introduce strong coupling between components ;-) |
|
@Krzysztof-Cieslak I just don't want to be in a position where we end up with out of date docs in one of the two repos. |
|
Referencing the quick start guide was my initial thought (as you may have recognized I 'lifted' the major part of the documentation from it). I adapted it a bit because I reckon that people working with the project don't have to necessarily be the ones who used the template to create it (finding it on GitHub, on the company SCM, etc). Also there are more (or different) options that should be documented in the README that would be too much for the quick start (like the docker or Azure build targets). I think it would be a good idea to reference the quick start guide right at the top to tell people that the application was created using the template in this quick and easy way. Also I'd add the dependency on the dotnet Core SDK again - I deleted it because I thought it would be obvious that people have it installed as they used the template but as of my own reasoning this doesn't have to be the case 😅 Would this be good or am I missing your point? |
|
Yeah - I think in this case, less is more with the readme - and what you're put here is way, way better than what we currently have, which is nothing. |
Content/README.md
Outdated
| @@ -0,0 +1,49 @@ | |||
| # SAFE Template | |||
|
|
|||
| This template can be used to generate a full-stack web application using the [SAFE Stack](https://safe-stack.github.io/). | |||
There was a problem hiding this comment.
Add a link here to the quick start as well, from which this is based upon?
|
|
||
| If you want to know more about the full Azure Stack and all of it's components (including Azure) visit the official [SAFE documentation](https://safe-stack.github.io/docs/). | ||
|
|
||
| ## Troubleshooting |
There was a problem hiding this comment.
I think you can remove this section - it's something that will be fixed (if it's not already fixed) relatively soon.
There was a problem hiding this comment.
Do you mean the Troubleshooting paragraph or the paragraph before that and the Troubleshooting paragraph?
There was a problem hiding this comment.
I think I saw newest SDK warning about that when installing a global tool, at least on a bare alpine-sdk2.1 docker image
There was a problem hiding this comment.
Ok I'll just leave it then for now.
| fake build -t Run | ||
| ``` | ||
|
|
||
| //#if (deploy == "docker") |
There was a problem hiding this comment.
I would personally remove the docker and app service bits - you need to really read the docs to understand how to use them both. Perhaps replace with a couple of links to those pages, or just remove.
- adds link to template documentation and quickstart at the top - adds dependency on dotnet core sdk in dependency section - changes docker and azure guides to additional conditional links to the docs - adds docs for other conditional dependencies like reaction, remoting, fulma, etc
|
LGTM, @isaacabraham do you have any other comments? |
|
LGTM - thanks again :-) |
As a user of the SAFE template I might want to have an initial Readme which tells me how to run/deploy the newly created application. I don't know how much value it adds as people learning about the template most likely do so from the SAFE documentation site but at least for other contributors or people who just find the repo in source control it could be helpful.