Missing documentation on some core stuff

dead-claudia commented 6 years ago

Edit: Not suggesting adding a FAQ page anymore, so I recast the issue. I've preserved the previous text in case you're curious what it was previously.

Old proposal

I'm collecting things for a potential FAQ page. I've got a few already, but I know there's got to be more between here and Gitter. This would include both TS-related and core Mithril-related stuff, so we have an easy, always-up-to-date page on commonly asked questions here. - Classes as component factories = bad: https://github.com/MithrilJS/mithril.js/issues/1926 - What `vnode.state` is in various places, including in the various component types as well as [in the vnode attrs themselves](https://github.com/MithrilJS/docs/issues/24) - this is probably second only to routing in its complexity, and it's tripped people up more than once. - ~~Why we include almost everything - [the excess isn't really as much as you might think](https://github.com/MithrilJS/mithril.js/issues/2187#issuecomment-402552570)~~ A conversation with @barneycarroll reminded me this isn't quite set in stone enough to be on a FAQ page as a canned answer.

There's a couple things I've found that need documented, and I'm pretty sure there's more that also need added.

Anti-pattern: Classes as component factories = bad: https://github.com/MithrilJS/mithril.js/issues/1926
What vnode.state is in various places, including in the various component types as well as in the vnode attrs themselves.
We need to show people how to install the typings and show them where to report typings issues. This hasn't shown up in the GH issues much, but many people have asked on Gitter where they are. It's not exactly obvious from the mithril.js.org website that we generally support them as a community-maintained thing, and I think we should fix that.

dead-claudia commented 6 years ago

@MithrilJS/collaborators I can't be the only one noticing patterns here with common questions. I plan to drop this by the Mithril Gitter, too, to see if I can get some more things to potentially add. I'm pretty sure we could get a pretty decently sized page of various frequently asked questions in various areas.

dead-claudia commented 6 years ago

BTW, I recast the main issue, since I've decided against adding a FAQ page. Just letting you all know.

dead-claudia commented 6 years ago

Related (and basically a better-thought-out dupe of my original idea): MithrilJS/mithril.js#2262

MithrilJS / docs

Missing documentation on some core stuff #22