wails documentation proposals

[bh90210]

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:

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]

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]

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]

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]

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]

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]

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

[bh90210]

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:

0. 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?).

• Intro
• https://github.com/wailsapp/wails#features
• https://github.com/wailsapp/wails#project-status
• https://github.com/wailsapp/wails#installation - we should correct it to prerequisites
• https://github.com/wailsapp/wails#installation-1 - this part I suggest to be replaced by the new quickstart (see bottom of the post)
• https://github.com/wailsapp/wails#next-steps
• https://github.com/wailsapp/wails#faq etc

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

• High level overview
• Frontend
• Backend
• Next steps

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:

• Go 1.12
• npm

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.

2. 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?

3. Generate new project:
   showcase wails init

4. Build it:
   showcase wails build

suggestion: maybe also briefly mention wails build -d?

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

suggestion: also include javascript equivalent for go code

6. Server it:
   Showcase wails serve

7. 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

• Introduction - a refined version High level overview (maybe with some addition from https://wails.app/reference/concepts.html yes am talking about the graphs! 🤣 )
• Prerequisites
• Installation
• New project / Build
• Events (expand on HelloWorld)
• Brief frontend development while serve
  next steps

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]

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).

• wails
  -- overview
  -- features
  -- concepts
  -- IPC overview
  -- binding - I am referring to https://wails.app/reference/concepts.html
  -- events - I'm referring to https://wails.app/reference/concepts.html
  -- anatomy of a project
  -- execution workflow
  -- ?
  -- ?

• quick start
  -- introduction
  -- prerequisites
  -- installation
  -- new project/build
  -- evetnts
  -- serve
  -- next steps

• reference
  -- API
  --- binding
  ---- functions
  ---- structs
  ---- rules
  ---- important detail
  --- runtime
  ---- events
  ---- emit
  ---- on
  ---- log
  ---- dialog
  ---- window
  ---- common pattern
  -- Cli
  --- help
  --- setup
  --- init
  --- serve
  --- build
  --- build flags
  --- update
  --- issue
  --- tooling - decouple from development section

• tutorials - this is already fine

• contributing/development - this is perfect, but as I said above I suggest moving the tootling section under Cli, because it makes more sense this way?
  -- background
  -- issue driven development
  -- branch workflow

• project status

[bh90210]

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 🚀