aurelia / aurelia/documentation

Improving vCurrent docs

Open
#456 9 comments 1 reaction 0 assignees View on GitHub
Dominant language
No language data
Stars
104
Forks
108
PR merge metrics
No merged PRs in 30d

Description

@EisenbergEffect following on from #443

### documenting lifecycles
* the order lifecycles are called between components (starting an App Root)
* how they are interleaved between different lifecycle (router vs component vs dialog)
* how to work around router bug https://github.com/aurelia/router/issues/612

### For each lifecycle hook
* its purposes
* explain what is available in each hook. For example `activate` because its called prior to `created` doesn't have anything injected yet. While these should be *obvious* its an example of "you can't see the forest, but for the trees" when you are focused on just this one lifecycle hook you forget how it relates to all the others. If the documentation includes that reminder it will be easier to recall that information.
* examples of what types of things should be done in each hook
* examples of what **NOT** to do in each hook

### Non trivial applications by example:

**Highlighting Navigation Menu**
* SPA with navigation menu on left
* current route (or active page) is highlighted in the navigation menu
* content selection causes changes in the route updating highlighted item in the navigation menu

**Menu handling**
* Dynamically creating drop down menus from Domain objects and separating into UI ViewModel structures for use by menus
* Highlighting active menu (and child menu item) - whose responsibility is it to manage that state?
* How to pass in `route-href` data when the menu structure is created including params binding

That'll do for a start.

I've got `vNext` checked out and looked into `docs/user-docs/` but I've yet to read anything in detail.

What's missing for me is the setup instructions for running and hosting the documents locally so that I can see them rendered. An equivalent of https://www.gatsbyjs.org/ would be tops!

Contributor guide

Open the contributing guide

Research direction

Begin in docs/user-docs/ and establish how the documentation is run and hosted locally, since the issue says those instructions are missing. Then map the requested lifecycle ordering, hook guidance, and navigation-menu examples into the docs; done means the rendered docs explain those topics and can be viewed locally.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.