-
-
Notifications
You must be signed in to change notification settings - Fork 924
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[braindump] Docs issues and suggestions #1687
Comments
Only |
@ feature/idea point: "@porsager suggested putting all the docs on one single page, so users can Ctrl-F their way to happiness"
|
any progress? |
@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.
Already done, minus the dedicated element.
Basically https://mithril.js.org/api.html.
See #2348.
Haven't looked into it yet.
Already done.
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.
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.
Issue's been known for a while: #1987
Done. I've updated the checkbox, too.
Done. I've updated the checkbox, too.
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.
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.)
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.
Not likely going to happen at that high of a level, but we do have it in the sidebar when you click "API".
This is mentioned on the main page.
This is one of the first things on the main page, barely below the fold.
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.)
Done.
Pretty simple PR to do. Just a single sentence needs added where REM is introduced to clarify this bit.
These four are all easy edits to make. Feel free to file a PR striking each of these from
Easy PR.
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.
Agreed. It also needs recast some to remove that opinion.
Nope, what's there is correct. It's "syntax sugar" and doesn't need fixed.
In reality, we should rip that out and just state "if you need to support IE, do this, but skip the JSX-specific parts".
See my response to the related section in "simple-application".
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.
The general advice is to just use JSDOM. If someone wants to file a PR to update that, more power to them.
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.
See my response to the line "link to FAQ / Caveat Emptors / "Something's wrong, where should I start to look" should be displayed prominently".
This is addressed a little more accurately in https://mithril.js.org/vnodes.html#avoid-memoizing-mutable-vnodes
It's now explicitly async.
See https://github.com/MithrilJS/mithril.js/issues/2375. It's under discussion how that's going to get resolved.
I'll accept a PR on this, but I'd like to wait for the signatures to get cleaned up first.
Irrelevant: removed in v2.
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. |
Wrt
... 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 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. |
@orbitbot We can have both ;) - example: http://pm2.keymetrics.io/docs/usage/pm2-doc-single-page/ |
Aaah, cake and a full stomach. Yeah, guess that might work if someone feels it's worth it. |
@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 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. |
@isiahmeadows following @porsager's suggestion obviates the reliance on external search engines. I think it's a really good idea! |
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... |
Also cleared the CSS up to be a lot more readable instead of smooshed into a single line.
- Addresses another part of MithrilJS#1687 - Also, fix a few linter issues in the ospec binary
* Fix #2414, address part of #1687 Also cleared the CSS up to be a lot more readable instead of smooshed into a single line. * Redo the testing docs page - Addresses another part of #1687 - Also, fix a few linter issues in the ospec binary * Add note about third-party cookies, tweak a line * Make the JSX comparison much more meaningful And let the code speak for itself. Don't fuel the flame wars any more than what they've already become. We should be *unopinionated*, and so I've updated those docs to remove the existing opinion. * Remove a bunch of outdated ES6 references * Remove the CSS page
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
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.
Bits and pieces exist, but #2348 consists of the bulk of the efforts.
Low-priority, but wouldn't take long to do.
Pull request accepted, if any of you all would like.
Low-priority, but would involve a bit of extra work to ensure it's compliant with privacy laws.
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.
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.
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.
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.
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.
Better: link to https://github.com/orbitbot/awesome-mithril/, which has this info.
Not a bad idea. If you'd like, feel free to file a PR adding the end result to
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.
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.)
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.
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.
See #2375
If this is pressing enough, feel free to create a pull request. It's low priority for me currently.
Still leaning towards "it's prominent enough". Streams could probably be documented a little more closely, while ospec is probably best pulled out entirely. |
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
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:
<div id="sth">
tomount
orrender
into? that's otherwise empty, f.e. at the beginning of each page?)m.route
vsm.render
vsm.mount
, vdom libs vs jquerymithril-awesome
list of relevant links)GH Readmes:
<br>
before each headline for better readability, docs site doesn't have this issue since it's handled with CSS marginslanding page
m()
has reserved object keys that breaks stuffinstallation
package.json
, likewise for other toolssimple-application
examples
in the GH repo, as a cheat sheet.jsx
es6
css
testing
all the pages under Key concepts
vnodes
changelog:
m.redraw
is not consistently async (yet?)m.request
.serialize -> request happens -> .extract -> .deserialize
" flow or something similar, there has been confusion about these methods (and perhaps others) on gitterm.withAttr
m.stream and ospec
The text was updated successfully, but these errors were encountered: