Improving vCurrent docs

[baerrach]

@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!

[EisenbergEffect]

I'd love to start out with the lifecycles bit. I've heard a lot of requests for clearer, centralized information around that. We can create a brand new document dedicated to just that. You want to go ahead and start with taking a stab at that?

[baerrach]

@EisenbergEffect I sure can.

Can you get me in touch with the tech writer as the first step will be to document how to write documents!

For example https://www.gatsbyjs.org/contributing/gatsby-style-guide/, and how to build locally.

[EisenbergEffect]

We don't have any documentation on how to write docs for v1. Mostly, you can write Markdown and then we can add the yaml metadata and help edit after you do a first draft. For v2, we have some basic guidance we've been putting in place, which you can see here: https://docs.aurelia.io/community-contribution/writing-documentation It's very much a work in progress.

[baerrach]

Excellent, I'll just follow with the v2 guidelines and apply what I can with v1.

Are v1 and v2 gitbooks? Are there instructions on what how to build and run a local version of the documentation?

[EisenbergEffect]

We started experimenting with GitBooks for v2. For v1, we have a custom generator. It's a bit of a pain to run honestly. My recommendation would be to just write straight markdown. Make it look correct on GitHub. I'll do an edit pass and fix up anything, and review it as it renders from our generator, so you don't need to worry too much about that.

[baerrach]

Are there docs on how to use gitbook locally?

There are no commands in package.json/scripts

https://docs.gitbook.com/ only talk about hosted options.

There are two npm packages gitbook and gitbook-cli.

I've tried using gitbook-cli to gitbook serve locally but its not building correctly in either the docs/ or docs/user-docs directories.

I can write the docs in the vNext area and serve via gitbook locally to see how they render and then publish them elsewhere. And aren't they needed for vNext as well?

[EisenbergEffect]

Only au2 is using Gitbooks. We are trying it out. I'm not sure they have a local option. I've only used it by editing Markdown on GH or by using their web interface (which is pretty decent). If you want to jump in and help with the au2 docs, I can add you to a community team and you can edit from the Gitbooks site directly. I wasn't sure if you wanted to work on the current docs or the au2 docs though. If you want to jump in in both places, I can get you set up. For au1, it's just Markdown in GH.

[baerrach]

I figured it is the same docs just with some polymorphs.

Let's add me as to the community team and I can see what the work flow looks like.

I'm hoping I can harvest the markdown from au2 docs as a starter for the au1 docs for improved efficiency.

[EisenbergEffect]

@baerrach Can you email me directly? rob at bluespire dot com We can pick up logistics convo there and it will be easier for me to get you access to Gitbooks.