Lacking documentation
asilverman opened this issue · 11 comments
I would like to use this template for my application, however there is no getting started guide or explanations regarding the proper use and extension of this template.
A Getting Started document and a simple overview of the design of the application would really go great lengths in making this more usable IMO.
Thanks for reporting this issue @asilverman!
I will try to come up with something.
@sagikazarmark this repo would become top1 scaffold in golang. I would like to help with documenting/cli or create a generator in yeoman if you want.
@anhntbk08 Thanks, any help is appreciated!
I'm trying to make this repo a better scaffold example, right now it's more like a living example.
I'm not familiar with yeoman TBH. As for CLI, I'm working on this one to help with code generation: https://github.com/sagikazarmark/mga
If you have any ideas for documentation structure please don't hold it to yourself. 🙂
@sagikazarmark I would be happy to also collaborate with documentation. Any ideas how I could help?
The primary reason I'm struggling with this is there are so many things we could write down, and I can't seem to be able to make order in the chaos. 🙂
I'm trying to find a basic structure, that I can follow and fill in with information.
I'm thinking about writing a TOC and polishing it to a point where I can actually start writing the documentation.
Something like this would probably be nice: https://github.com/short-d/short
Either in the main repo or in wiki?
These are the high level topics I'd like to touch:
- Quickstart
- Architecture
- Component structure
- Application development use cases
- Tools
- FAQ
I guess a little brainstorming what you would like to see would definitely help. 🙂
@sagikazarmark Hi Mark, I've been looking through the makefile deployment and packaging.
Can't wrap my head around it.
- Do I need pkger if I don't have static redistributable?
- What is the pkg folder for?
@Dmdv No, you don't need pkger then, but this example project comes with a static home page. I'll soon replace it with Go 1.16 embed.
As for the pkg folder: it's a placeholder for reusable packages that doesn't contain domain specific code. For example: if you have a function for retrying failed function calls, you'd put it in pkg/retry instead of internal or cmd.
@sagikazarmark Thank you
@sagikazarmark As for pkg - nice point.
Though, there could be also helpers and other cross-cutting concerns like logging, monitoring, etc.
Is the internal folder the right place all in or still the pkg folder would be the right place?
Does logging go to the pkg folder or stay in the log folder?
It depends, I could argue for both. I usually put them in internal/platform, because they are not exactly reusable packages, but internal to the application (eg. an application specific interface and an adapter in case of this repo). But they could be reusable packages.
@sagikazarmark Ah, I see, makes sense, right