search

wailsapp / wails

Create beautiful applications using Go
https://wails.io
MIT License
24.73k stars 1.19k forks source link

wails documentation proposals #125

Closed bh90210 closed 5 years ago

bh90210 commented 5 years ago

A I am going through https://wails.app/reference/guide.html and I find myself constantly scrolling up and down to understand where I am at.

It would be really helpful if the template changed a bit to introduce a right sidebar showing you where you at. This screen taken from android documentation as an example: android_doc_example wails_doc_example

B Installation instructions (and maybe helloWorld?) should be part of the quickstart to follow the convention of most quickstart pages? for example https://grpc.io/docs/quickstart/go/

C at the moment the guide explains wails around a vue project. maybe somehow generalise? (or include the rest of the default supported frontend frameworks? although this sounds like overkill it only needs to be done once and for people coming from vue, react etc will actually be really helpful, for the rest I am not so sure, so generalisation I believe is more apt.)

D maybe https://wails.app/reference/guide.html would be better if it brakes down to two different parts

  1. the guide as as is to explain template's anatomy and basic concepts and
  2. from https://wails.app/reference/guide.html#binding onwards maybe should be under its own sub (ie. API)?

E (bug) there is a navigation issue. from the https://wails.app/reference/ page when I click https://wails.app/reference/#guide instead of going to the guide as I would expect I am still on the same page at #guide tag. Then I have to click again to reach the actually guide, but also the left side menu collapses once I reach the page.

leaanthony commented 5 years ago

Fantastic suggestions! We use vuepress for the docs so I'll have a look to see what template options there are. Or maybe you know of a better tool?

bh90210 commented 5 years ago

one more thing, it would also be really helpful if in the #binding section of the the guide https://wails.app/reference/guide.html#binding wherever is applicable to have complementary plain javascript code samples along the respective go snippet examples.

bh90210 commented 5 years ago

I have never used something myself so I have no suggestions, what I would like to use at some point is Hugo but seems overkill for just a menu essentially plus since you have already decided to use vuepress the functionality is already there, namely the left sidebar does exactly what we need, just needs a custom template and it's good.

leaanthony commented 5 years ago

I'm very happy to move to Hugo and looked extensively for templates that were designed for technical documentation. I didn't find any good ones :-)

Regarding the above, I can now comment on each point.

A: If vuepress supports it, we can do it :-) B: Agree with this! It's amazing how many people didn't have npm installed because it wasn't explicitly in the platform instructions C: At the time, only Vue was available. Generalisation is definitely preferred to maintaining multiple framework docs D: I was actually considering this as I was updating it yesterday, so yes! E: Yeah, this was kinda a workaround for the way Vuepress works. It was a super low priority to fix it.

The binding section will be updated as part of this ticket.

The real takeaway from this comment is this: I accept PRs on the docs repo 😂

bh90210 commented 5 years ago

from a quick search yesterday I found this one to be potentially useful https://themes.gohugo.io//theme/hugo-book/docs/shortcodes/ layout for working on

leaanthony commented 5 years ago

That looks good. Code with line numbers is essential too.

bh90210 commented 5 years ago

Urgent

Before extrapolating on my proposal these are my reference projects: https://grpc.io/docs/quickstart/go/ https://gohugo.io/getting-started/quick-start/ https://docs.dgraph.io/get-started/ https://docs.docker.com/get-started/ https://prometheus.io/docs/introduction/first_steps/ https://gobuffalo.io/en/docs/getting-started/installation https://docs.syncthing.net/intro/getting-started.html

Quickstart:

  1. Introduction: First of all I believe we are not mentioning at all any installation instructions on the website https://wails.app https://wails.app/home.html#prerequisites & https://wails.app/home.html#installation Prerequisites and install instructions exist only on github's readme (also I believe there is a mistake there as well, instead of prerequisites & installation we write installation & installation https://github.com/wailsapp/wails#installation https://github.com/wailsapp/wails#installation-1). Overall github's readme is structured really good though I suggest we keep it as is and focus on the website (or maybe we could also use github's wiki?).

On wails website at the moment the quickstart section is like this: Quick start

I suggest to keep everything in this tab https://wails.app/quick_start.html#high-level-overview as part of an introduction and then proceed to prerequisites:

  1. Prerequisites: 
    Go 1.12
npm

    My suggestion here is to include an optional command in the instructions for users to run that checks both go and npm version to catch for exampe npm-less installs.

ie.

Wails uses cgo to bind to the native rendering engines so a number of platform dependent libraries are needed as well as an installation of Go. The basic requirements are:

Run go version && npm --version to verify.

then proceed to os dependencies prerequisites.

My suggestion here is instead of having every dependency for every supported os one under the next, make a menu for user to choose their os.

  1. Installation:

suggestion 1 be a little more vanilla regarding this line Ensure Go modules are enabled: GO111MODULE=on and go/bin is in your PATH variable.

for example:

Ensure Go modules are enabled: 

$ export GO111MODULE=on

and go/bin is in your PATH variable:

$ echo $PATH | grep go/bin

suggestion 2 include wails setup as finishing part of the installation?

  1. Generate new project: showcase wails init

  2. Build it: showcase wails build

suggestion: maybe also briefly mention wails build -d?

  1. Showcase very briefly adding a new element ie. WailsInit(runtime *wails.Runtime)

suggestion: also include javascript equivalent for go code

  1. Server it: Showcase wails serve

  2. Next steps:

suggestion: give the user 4 options - links

  1. a. Explore default templates or b. create custom.
  2. Concepts (expanding quick start's high level overview) https://wails.app/reference/concepts.html
  3. Cli reference
  4. API (?) reference

note about 1. a. will link to existing tutorials and guides and b. will link to https://wails.app/development/#tooling which I also suggest to get decoupled from https://wails.app/development/#development

So to conclude my final proposal, the new quick start structure is:

Quick Start

Non urgent I also started working on porting docs to Hugo https://github.com/bh90210/wails-docs/commit/4f979978dad9cb60c9110f29d760c4ff9a86a7fe we'll see how this goes. The various HTML things that need "fixing", ie. additional side menu, can be potentially addressed here.

bh90210 commented 5 years ago

in an attempt to clarify here is a proposal for a rearrangement of documentation that makes docs as a whole more neat/predictable (in the absolute positive sense).

bh90210 commented 5 years ago

I'm closing it as non-productive anymore? the latest pull in the documents addresses most of the proposals. at the moment the only major thing running is moving to hugo which is not urgent and also I am on to it. When I have something more mature I will open a new ticket :rocket: