[braindump] Docs issues and suggestions

[orbitbot]

This is a braindump issue over suggestions regarding the docs that can be improved on, on different levels. All IM(H)O, of course, so consume with the appropriate sodium nitrate dose (colloquially, a pinch). I've read through the entire docs twice approximately twice about a month or so apart, and have been paying attention to related discussions (although not in a completely structured manner) on the gitter chat, so apologies for the wall of text... Feel free to chip in with your own observations etc. In the second read-through just now, I did skim quite a bit (fe. most of the code content).

Features / ideas:

• someone suggested on gitter that mithril should be loaded on each page, so people can open the console and start playing around a bit (perhaps with dedicated <div id="sth"> to mount or render into? that's otherwise empty, f.e. at the beginning of each page?)
• @porsager suggested putting all the docs on one single page, so users can Ctrl-F their way to happiness
• add jsbins/fiddles/playcodes either (or also) as links or embedded iframes for end users to play with examples (if appropriate, the current content is relatively static). Maybe at least the landing page example?
• have a favicon
• clicking on a headline should add the hash to the page URL, enables relevant deep linking, GH readmes do this and it's really convenient
• perhaps a bullet-point conceptual page? eg. m.route vs m.render vs m.mount, vdom libs vs jquery
• put something like GA on the docs to track how people are finding the pages (referring urls etc), where they spend time etc. for future improvements
• remove the wiki from the site, since everything is mostly 0.2-related, replace with properly featured content on the site, or community-run separate repos (eg. a mithril-awesome list of relevant links)

GH Readmes:

• GH main README should not be the same content as the docs landing page, users are likely to have separate concerns if they're on GH and can be redirected to the website. GH README should rather contain contribution instructions, bug filing and suchlike
• GH readmes could do with a bit better vertical spacing, eg. adding <br> before each headline for better readability, docs site doesn't have this issue since it's handled with CSS margins

landing page

• quick answers : what, why, how
• quick answers : browser support, payload size
• discoverability: what information is where
  • almost provides full sitemap, however API section left navigation content would also need to be shown, would ideally not be only a vertical list since it's a bit tedious to navigate
  • even with current sidebars, it's not completely obvious where to look for specific information, until you've already read it once, eg. important info hidden at the end of long pages
• IMO landing page could just have a very brief snippet of how to, defer guides to other pages and be more about
  • elevator pitches ("learn the full API in 2 days", that quote about being hit by a bus that I forgot to copy somewhere safe)
  • display site content map
  • perhaps even a "how to read this website" section, fe. what to cover in what order in 3-5 sessions
• link to FAQ / Caveat Emptors / "Something's wrong, where should I start to look" should be displayed prominently
  • m() has reserved object keys that breaks stuff
  • end users need to enable 3rd party cookies for REM to work
  • don't worry about blocking redraws in most cases (bears repeating, since it's a common question)
• projects that have "grown out" of the mithril rewrite and that are now published as individual npm packages (ospec, mithril-stream) should be more prominently displayed (eg. conceptually perhaps on the Guide | API | Chat | Github level)

installation

• if mithril is loaded on each page (suggested above), mention that it is available in the browser console
• link to a basic fiddle/bin
• defer or link to npm documentation on package.json, likewise for other tools
• link to existing mithril setup projects (insofar such exist for 1.0)
• don't suggest mithril's bundler as a viable end user tool for projects, since it's likely to break. The text content leaves this impression already

simple-application

• the source code for the end result should be available under examples in the GH repo, as a cheat sheet.
• 3rd party cookies need to be enabled (noted above) for REM to work properly
• "Regardless of what CSS convention/library you choose, a good rule of thumb is to avoid the cascading aspect of CSS." -- citation needed / needlessly opinionated / unsubstantiated
• "Plain CSS can be sufficient for low-complexity projects (e.g. 3 to 6 man-months of initial implementation time and few project phases)." -- arbitrary project size scoping & opinion is arbitrary, see previous point
• "The CSS above is written using a convention of keeping all styles for a rule in a single line, in alphabetical order. This convention is designed to take maximum advantage of screen real estate, and makes it easier to scan the CSS selectors (since they are always on the left side) and their logical grouping, and it enforces predictable and uniform placement of CSS rules for each selector." -- also, highly unconventional (IME), suffers from readability issues in comparison to normally formatted CSS and end user cannot deduce what's going on "at a glance" but must rather read full code
• "The example above is just an illustration of a not-so-widespread convention that has strong rationales behind it, but deviate from the more widespread cosmetic-oriented spacing conventions." -- comes off a bit arrogant

jsx

• "on your team's preferences." => "on your or your team's preferences."
• babel instructions are likely to become outdated eventually... (also relevant for other parts of the guide that are not mithril-specific)
• as someone mentioned on gitter at some point, this whole page reads like: "Here's JSX and how you use it, here's why you probably shouldn't be using it"

es6

• "introduces new syntax sugar" => syntactical sugar (not 100%, I only play a native speaker on the Interwebs)
• => "you or your team's" as above
• same caveat regarding babel instructions as elsewhere, also content seems to be more or less identical, so will probably diverge with the other pages over time (unless there's a single source file somewhere)

css

• mostly reads as unsubstatiated opinions
• page should perhaps rather focus on how to use the different approaches with mithril, otherwise it seems a bit out of place considering the context of the website

testing

• good testing practices reads like author never writes tests as they go along, or is familiar with BTDD (and similar) approaches for code development
• from gitter: should include instructions on how to mock browser APIs in node
• should include a section on integration testing, but I get the feeling no one (of gitter regulars at least) actually does this even superficially (Sencha.JS, PhantomJS, NightmareJS, protractor, etc.)

all the pages under Key concepts

• antipatterns could be collected in separate FAQ / Caveat page (suggested above), it's not obvious that these pages contain important info (almost as footnotes) unless you already know that they're there and as a user spend the time reading the full documentation to start with (which is perhaps feasible in this case, but not necessarily something to assume)

vnodes

• should mention caveat that it's quite likely a user error to pass the same object keys into a vnode, perhaps with workaround https://gitter.im/lhorie/mithril.js?at=58bea9adf1a33b62758f7851

changelog:

• to my understanding, m.redraw is not consistently async (yet?)
• returning objects from oninit is not meaningful, re: 0.2 controller patterns. this could perhaps be expanded on a bit in text (from gitter on 0.2 => 1.0 migration)

m.request

• especially here, the signature table is quite difficult to read and it's quite easy to miss details, this is also relevant elsewhere
• should probably add a "pass data to .serialize -> request happens -> .extract -> .deserialize" flow or something similar, there has been confusion about these methods (and perhaps others) on gitter

m.withAttr

• could add note about how this might quite easily be made redudant with es6 arrow functions

m.stream and ospec

• as noted above, should be more prominently featured on the site

[orbitbot]

Only m.route and m.stream are affected by this, since they seem to be the only parts of the API that are particularly overloaded, but it would be really beneficial to immediately be able to see an overview of both the default signature and the static members instead of scrolling (particularly in the stream case) the whole page looking for whatever that method was called again. Partially touched upon above already.

[salamynder]

@ feature/idea point: "@porsager suggested putting all the docs on one single page, so users can Ctrl-F their way to happiness"

• full text search which points to appropriate topics would be nicer (cf. webpack.js.org -> search tool)

[talentlessguy]

any progress?

[dead-claudia]

@talentlessguy and others interested: Here's the status on most of them.

Click to expand (it's long)

I will note before I proceed that I've been wanting to overhaul the Mithril docs in both prose and design for quite some time, but just haven't gotten around to the months of effort required in all this.

Features / ideas:

• someone suggested on gitter that mithril should be loaded on each page, so people can open the console and start playing around a bit (perhaps with dedicated <div id="sth"> to mount or render into? that's otherwise empty, f.e. at the beginning of each page?)

Already done, minus the dedicated element.

• @porsager suggested putting all the docs on one single page, so users can Ctrl-F their way to happiness

Basically https://mithril.js.org/api.html.

• add jsbins/fiddles/playcodes either (or also) as links or embedded iframes for end users to play with examples (if appropriate, the current content is relatively static). Maybe at least the landing page example?

See #2348.

• have a favicon

Haven't looked into it yet.

• clicking on a headline should add the hash to the page URL, enables relevant deep linking, GH readmes do this and it's really convenient

Already done.

• perhaps a bullet-point conceptual page? eg. m.route vs m.render vs m.mount, vdom libs vs jquery

There's a little bit at https://mithril.js.org/framework-comparison.html for other frameworks, but we haven't yet looked into something like this.

• put something like GA on the docs to track how people are finding the pages (referring urls etc), where they spend time etc. for future improvements

Been privately considering, but I haven't gotten around to it yet. I'll have to figure out a means of lazy-loading for consent first.

• remove the wiki from the site, since everything is mostly 0.2-related, replace with properly featured content on the site, or community-run separate repos (eg. a mithril-awesome list of relevant links)

Issue's been known for a while: #1987

GH Readmes:

• GH main README should not be the same content as the docs landing page, users are likely to have separate concerns if they're on GH and can be redirected to the website. GH README should rather contain contribution instructions, bug filing and suchlike

Done. I've updated the checkbox, too.

• GH readmes could do with a bit better vertical spacing, eg. adding <br> before each headline for better readability, docs site doesn't have this issue since it's handled with CSS margins

Done. I've updated the checkbox, too.

landing page

• quick answers : what, why, how
• quick answers : browser support, payload size
• discoverability: what information is where
  • almost provides full sitemap, however API section left navigation content would also need to be shown, would ideally not be only a vertical list since it's a bit tedious to navigate
  • even with current sidebars, it's not completely obvious where to look for specific information, until you've already read it once, eg. important info hidden at the end of long pages
• IMO landing page could just have a very brief snippet of how to, defer guides to other pages and be more about
  • elevator pitches ("learn the full API in 2 days", that quote about being hit by a bus that I forgot to copy somewhere safe)

I've considered this for a while, just haven't actually gotten around to it thanks to various things, including getting v2 out the door.

• display site content map
• perhaps even a "how to read this website" section, fe. what to cover in what order in 3-5 sessions

This has been discussed in various places, but it's back burner for now. Any serious changes are probably not going to happen until well after v2. (I'd like to wait until the dust settles first before progressing.)

• link to FAQ / Caveat Emptors / "Something's wrong, where should I start to look" should be displayed prominently

The "how" in how it should be presented has probably been the most contentious. The discussion stalled after a few months straight of just continuous debate in various issues, so this is why nothing has materialized yet.

• m() has reserved object keys that breaks stuff
• end users need to enable 3rd party cookies for REM to work
• don't worry about blocking redraws in most cases (bears repeating, since it's a common question)
• projects that have "grown out" of the mithril rewrite and that are now published as individual npm packages (ospec, mithril-stream) should be more prominently displayed (eg. conceptually perhaps on the Guide | API | Chat | Github level)

Not likely going to happen at that high of a level, but we do have it in the sidebar when you click "API".

installation

• if mithril is loaded on each page (suggested above), mention that it is available in the browser console

This is mentioned on the main page.

• link to a basic fiddle/bin

This is one of the first things on the main page, barely below the fold.

• defer or link to npm documentation on package.json, likewise for other tools
• link to existing mithril setup projects (insofar such exist for 1.0)

If someone wanted to link to https://github.com/orbitbot/awesome-mithril, that would be sufficient IMHO. Userland stuff evolves a lot faster than Mithril itself does, so that would work better. (We should also maybe consider moving tutorials over there.)

• don't suggest mithril's bundler as a viable end user tool for projects, since it's likely to break. The text content leaves this impression already

Done.

simple-application

• the source code for the end result should be available under examples in the GH repo, as a cheat sheet.
• 3rd party cookies need to be enabled (noted above) for REM to work properly

Pretty simple PR to do. Just a single sentence needs added where REM is introduced to clarify this bit.

• "Regardless of what CSS convention/library you choose, a good rule of thumb is to avoid the cascading aspect of CSS." -- citation needed / needlessly opinionated / unsubstantiated
• "Plain CSS can be sufficient for low-complexity projects (e.g. 3 to 6 man-months of initial implementation time and few project phases)." -- arbitrary project size scoping & opinion is arbitrary, see previous point
• "The CSS above is written using a convention of keeping all styles for a rule in a single line, in alphabetical order. This convention is designed to take maximum advantage of screen real estate, and makes it easier to scan the CSS selectors (since they are always on the left side) and their logical grouping, and it enforces predictable and uniform placement of CSS rules for each selector." -- also, highly unconventional (IME), suffers from readability issues in comparison to normally > formatted CSS and end user cannot deduce what's going on "at a glance" but must rather read full code
• "The example above is just an illustration of a not-so-widespread convention that has strong rationales behind it, but deviate from the more widespread cosmetic-oriented spacing conventions." -- comes off a bit arrogant

These four are all easy edits to make. Feel free to file a PR striking each of these from docs/simple-application.md. (I may end up doing it myself.)

jsx

• "on your team's preferences." => "on your or your team's preferences."

Easy PR.

• babel instructions are likely to become outdated eventually... (also relevant for other parts of the guide that are not mithril-specific)

We can always keep this updated manually. We could eventually link to Babel's site, but only once we have things correctly clarified. I also have a few things I need to test first.

• as someone mentioned on gitter at some point, this whole page reads like: "Here's JSX and how you use it, here's why you probably shouldn't be using it"

Agreed. It also needs recast some to remove that opinion.

es6

• "introduces new syntax sugar" => syntactical sugar (not 100%, I only play a native speaker on the Interwebs)

Nope, what's there is correct. It's "syntax sugar" and doesn't need fixed.

• => "you or your team's" as above
• same caveat regarding babel instructions as elsewhere, also content seems to be more or less identical, so will probably diverge with the other pages over time (unless there's a single source file somewhere)

In reality, we should rip that out and just state "if you need to support IE, do this, but skip the JSX-specific parts".

css

• mostly reads as unsubstatiated opinions
• page should perhaps rather focus on how to use the different approaches with mithril, otherwise it seems a bit out of place considering the context of the website

See my response to the related section in "simple-application".

testing

• good testing practices reads like author never writes tests as they go along, or is familiar with BTDD (and similar) approaches for code development

Well, in my experience, Leo Horie, the original author, really didn't until we got bit hard multiple times in the v0.2 era, and I still didn't get the impression he fully understood it in his v1 rewrite.

I'm open to a recast of that particular file.

• from gitter: should include instructions on how to mock browser APIs in node

The general advice is to just use JSDOM. If someone wants to file a PR to update that, more power to them.

• should include a section on integration testing, but I get the feeling no one (of gitter regulars at least) actually does this even superficially (Sencha.JS, PhantomJS, NightmareJS, protractor, etc.)

I've done it on some level with Cucumber, but it was at a high enough level it was entirely framework-agnostic.

It's also worth noting that not even React provides this in their docs.

all the pages under Key concepts

• antipatterns could be collected in separate FAQ / Caveat page (suggested above), it's not obvious that these pages contain important info (almost as footnotes) unless you already know that they're there and as a user spend the time reading the full documentation to start with (which is perhaps feasible in this case, but not necessarily something to assume)

See my response to the line "link to FAQ / Caveat Emptors / "Something's wrong, where should I start to look" should be displayed prominently".

vnodes

• should mention caveat that it's quite likely a user error to pass the same object keys into a vnode, perhaps with workaround https://gitter.im/lhorie/mithril.js?at=58bea9adf1a33b62758f7851

This is addressed a little more accurately in https://mithril.js.org/vnodes.html#avoid-memoizing-mutable-vnodes

changelog:

• to my understanding, m.redraw is not consistently async (yet?)

It's now explicitly async.

• returning objects from oninit is not meaningful, re: 0.2 controller patterns. this could perhaps be expanded on a bit in text (from gitter on 0.2 => 1.0 migration)

m.request

• especially here, the signature table is quite difficult to read and it's quite easy to miss details, this is also relevant elsewhere

See https://github.com/MithrilJS/mithril.js/issues/2375. It's under discussion how that's going to get resolved.

• should probably add a "pass data to .serialize -> request happens -> .extract -> .deserialize" flow or something similar, there has been confusion about these methods (and perhaps others) on gitter

I'll accept a PR on this, but I'd like to wait for the signatures to get cleaned up first.

m.withAttr

[...]

Irrelevant: removed in v2.

m.stream and ospec

• as noted above, should be more prominently featured on the site

They're prominent enough for now. I'll consider in a docs redesign making them more prominent and easier to find and discover, but that's not something of high priority.

[orbitbot]

Wrt

@porsager suggested putting all the docs on one single page, so users can Ctrl-F their way to happiness

Basically https://mithril.js.org/api.html.

... I believe the original intent by @porsager was perhaps more to have something like https://rollupjs.org/guide/en/ , so that everything can be searched in the browser itself. Personally I've tended to use google with site:mithril.js.org <searchterm> which works well enough, albeit I probably have a decent recollection of the appropriate terminology.

Not really a fan of neverending webpages from a reading perspective, personally, so ideally some kind of search functionality might be neater, though that'd require some kind of infrastructure addition I guess.

[porsager]

@orbitbot We can have both ;) - example: http://pm2.keymetrics.io/docs/usage/pm2-doc-single-page/

[orbitbot]

Aaah, cake and a full stomach. Yeah, guess that might work if someone feels it's worth it.

[dead-claudia]

@orbitbot @porsager Okay, I see what you all are referring to now. I'd be open to a generated single-page document exposed through the main navigation, with a header giving the tip of "If you want to search for something a little more advanced, try using site:mithril.js.org <query> in your favorite search engine". We'd also need to drop a robots.txt that prevents that page from being indexed, so we can point people to the standard pages.

I've seen a lot of docs sites lately using Agolia to a similar end lately (like Babel and Vue), but I'm hesitant to add a full third-party search engine plugin just to enable a basic text search of various docs.

[barneycarroll]

@isiahmeadows following @porsager's suggestion obviates the reliance on external search engines. I think it's a really good idea!

[orbitbot]

Probably not really worth the effort, but I guess it would be feasible to do full clientside search if the whole docs site would be SPA'd, especially with some page containing the whole documentation...

[dead-claudia]

@orbitbot Maybe we could use this and feed it parsed data from the docs. (I just found it minutes ago.) I could make sure it loads early enough in the background to not delay search too much, and I'd only need a service worker to cache the search index (to avoid unnecessary network requests).

[dead-claudia]

So new update: here's the items remaining, of @orbitbot's original list. Everything else has been addressed, either resolved and published (most of them) or rejected entirely.

Click to expand

Features / ideas:

• @porsager suggested putting all the docs on one single page, so users can Ctrl-F their way to happiness

Some discussion started here, and I don't think we're going to do this single page, but instead incorporate a proper offline text search.

• add jsbins/fiddles/playcodes either (or also) as links or embedded iframes for end users to play with examples (if appropriate, the current content is relatively static). Maybe at least the landing page example?

Bits and pieces exist, but #2348 consists of the bulk of the efforts.

• have a favicon

Low-priority, but wouldn't take long to do.

• perhaps a bullet-point conceptual page? eg. m.route vs m.render vs m.mount, vdom libs vs jquery

Pull request accepted, if any of you all would like.

• put something like GA on the docs to track how people are finding the pages (referring urls etc), where they spend time etc. for future improvements

Low-priority, but would involve a bit of extra work to ensure it's compliant with privacy laws.

• remove the wiki from the site, since everything is mostly 0.2-related, replace with properly featured content on the site, or community-run separate repos (eg. a mithril-awesome list of relevant links)

I've considered it, but it needs migrated somewhere else and archived first. I would like to keep one page, the "Who uses Mithril" page. Beyond that, part of this is tracked in #1987.

landing page

• discoverability: what information is where
  • almost provides full sitemap, however API section left navigation content would also need to be shown, would ideally not be only a vertical list since it's a bit tedious to navigate
  • even with current sidebars, it's not completely obvious where to look for specific information, until you've already read it once, eg. important info hidden at the end of long pages

Agreed that this is an issue, but it'd require a full site redesign to fix it. So don't expect it to happen especially quickly.

• IMO landing page could just have a very brief snippet of how to, defer guides to other pages and be more about
  • elevator pitches ("learn the full API in 2 days", that quote about being hit by a bus that I forgot to copy somewhere safe)
  • display site content map
  • perhaps even a "how to read this website" section, fe. what to cover in what order in 3-5 sessions

I'd like to do this, but I'd need to redo the site almost entirely from scratch to create such a linear progression. It's worth noting that React is the exception in having done this, not the norm.

• link to FAQ / Caveat Emptors / "Something's wrong, where should I start to look" should be displayed prominently
  • don't worry about blocking redraws in most cases (bears repeating, since it's a common question)

Maybe a small expert system-like thing could help here, not too unlike what RxJS has for selecting operators. It'd take time to code, but it'd be infinitely useful to a lot of people.

There's a few other places where I would like to employ a similar concept, too.

installation

• defer or link to npm documentation on package.json, likewise for other tools

This is a good idea, but I don't want to link to everything. It should still be easy for users to see how it all fits together.

• link to existing mithril setup projects (insofar such exist for 1.0)

Better: link to https://github.com/orbitbot/awesome-mithril/, which has this info.

simple-application

• the source code for the end result should be available under examples in the GH repo, as a cheat sheet.

Not a bad idea. If you'd like, feel free to file a PR adding the end result to examples/simple-application/.

testing

• should include a section on integration testing, but I get the feeling no one (of gitter regulars at least) actually does this even superficially (Sencha.JS, PhantomJS, NightmareJS, protractor, etc.)

Maybe a small section giving an overview with a bunch of links to elsewhere, but I'd rather not go into too much detail, or it'd quickly grow to about 80% of the entire page.

all the pages under Key concepts

• antipatterns could be collected in separate FAQ / Caveat page (suggested above), it's not obvious that these pages contain important info (almost as footnotes) unless you already know that they're there and as a user spend the time reading the full documentation to start with (which is perhaps feasible in this case, but not necessarily something to assume)

Can't seem to find the discussion, so if someone would like, feel free to file a bug. I'd like to maybe get actual discussion going on GitHub rather than just informally in Gitter. (That's where most of the arguments occurred - over there.)

vnodes

• should mention caveat that it's quite likely a user error to pass the same object keys into a vnode, perhaps with workaround https://gitter.im/lhorie/mithril.js?at=58bea9adf1a33b62758f7851

Might be a good idea to mention that. I'm leaning towards not checking it as it's too costly, but it would be a good idea to at least mention.

changelog:

• returning objects from oninit is not meaningful, re: 0.2 controller patterns. this could perhaps be expanded on a bit in text (from gitter on 0.2 => 1.0 migration)

I feel this is sufficiently implied, but if it's not, I'll accept a pull request that clarifies this further in the migration docs.

m.request

• especially here, the signature table is quite difficult to read and it's quite easy to miss details, this is also relevant elsewhere

See #2375

• should probably add a "pass data to .serialize -> request happens -> .extract -> .deserialize" flow or something similar, there has been confusion about these methods (and perhaps others) on gitter

If this is pressing enough, feel free to create a pull request. It's low priority for me currently.

m.stream and ospec

• as noted above, should be more prominently featured on the site

Still leaning towards "it's prominent enough". Streams could probably be documented a little more closely, while ospec is probably best pulled out entirely.