Bring back the old docs


#1

I liked being able to search one giant page for anything I needed. The new separated layout is less user friendly and the lower contrast between text and background is making it harder to read as well.


#2

Hmm, in theory, we could generate one giant page with everything via layouts, is it right @sashko?


#3

I think first we want to launch good search (by the end of this week) and see if that solves the problem? Although I’m not working on this so it’s better to ask someone else like @tmeasday or @domyen.


#4

Yeah, while they are pretty, they are also pretty hard to traverse.

I realized that while I was writing this I was complaining without any useful feedback, so yes, a better search would make the docs better IMO.

As an aside, I think that the Stripe documentation is the best api documentation on the internet.


#5

If you’re developing on OS X, do yourself a large favour and get a copy of Dash. The Meteor docs are available (along with just about every other open source project you can think of), you always have an offline copy handy, and the search is excellent.


#6

I love the new look, but also miss searching a whole page. I’m looking forward to that search feature!


#7

Checkout the existing docs thread for more color. @nerdmed had good insight in his comment.
https://forums.meteor.com/t/contributing-to-meteor-documentation/23492/20?u=domyen&source_topic_id=23818

Here’s a summary of what’s next:

  • Search is prioritized for the next release. It’s robust, convenient, lightning fast, and doesn’t require exact text matches to show relevant results. I think it’s a big improvement that addresses the cmd+f use case and also scales with the volume of docs content.
  • One-page docs has been requested and is being tracked in the issue tracker for Meteor’s open source docs theme. @tmeasday has already identified some todos. I’m sure he’d love an assist if folks have a spare cycle. :wink:

The docs UI is the tip of the iceberg of a larger docs project. Some of the goals of that project are to make community contributions easier and unify the way docs & guide are maintained. This past release marks our first step toward those goals.

Github
Docs UI aka hexo-theme-meteor issues:
Docs content issue tracker
Guide content issue tracker


#8

v1 of docs search is now live. Please help report issues against the styling/layout here or the content here.


#9

@domyen and everyone else @ MDG who is working on this. BIG THANK YOU for being so fast and bringing back a search! I already tried it out and it helps a lot! Even though i think the one page feature would be great in some cases.

I have some feedback regarding the user interface, is the Docs UI issue tracker right for this kind of feedback or somewhere else?

PS.: Algolia is a really great choice!


#10

Cheers! Docs UI issues are being tracked in the hexo-theme-meteor repo.


#11

God no! The full Stripe API reference is terrible, performance-wise. I’m on a 6-core 3.5GHz Mac Pro (“trashcan”), and that page is rather slow and choppy when I scroll (Chrome). Way too much content all on one page.


#12

old docs seems better.

I have old and new open side by side at the moment…

The new docs seem a bit weird when rendering, it feels a bit clunky.Every time it renders, it takes a while, and the side menu text seems to do magical shrinking for some reason.

Much faster navigating to any section with the old docs. Much much much faster. Also does so smoothly… rerendering is jarring in new docs.

Font/text seems harder to read in new docs, everything seems a bit bright/whitewashed. Using full page width makes it harder to read

The coloring of keywords is better in new docs


#13

also some links navigate the current page, some links open new pages, and some links do nothing…


#14

I’ve never heard that complaint before. That reference is the exact page I was talking about when I said I think they have the best documentation.

I really like all the content being on the same page as well as all the different languages that implement the calls. I had never run into any performance issues while using that page.


#15

Really? On two separate Macs of mine, that page is very choppy.

EDIT: Safari is smooth as butter. So is Firefox. So it’s a Chrome thing I guess.

EDIT 2: Canary is a little snappier than Chrome, but only marginally.


#16

This change to the docs has been a long, long, long time coming. We’ve had tons of ideas for various docs improvements in the past - improved contribution ability, code snippets, inline discussion, smarter search, combining docs from multiple repos/packages, and what have you.

Many of those were blocked (theoretically possible, but too much work and hard to maintain) because of the fact that it was one ultra-long page with sketchy hash URLs, custom JavaScript scrolling, etc. I think this refactoring, while annoying at first because some things are lost, will end up unblocking a ton of great stuff and make the docs a much more valuable resource long term.


#17

Hmm… There is some work left to do it seems :wink:

I just went into the guide and searched for an old friend of mine: isAppTest.

Nothing was found. Ctrl-F finds it (because I know where to look) in the “The ‘meteor test’ command” section
(which by the way I cannot link to now because the browser context menu is disabled on the anchor link).

Issue #35 submitted.


#18

Yeah, PLUS ONE for a great search-function.

I LOVED the big-old-docs and the abilite to quickly scan it by Ctrl-F! Right now browsing the docs takes to much brainpower for just searching for the right thing.


#19

The search is nice and fast :grin:, but perhaps a format that supports Ctrl+F would be good too. For UX Ctrl+F searching is consistent with the rest of a users web browsing experience, making it more familiar/faster/less frustrating to use.

Also the width of the text should be constrained so as not to fill the entire screen. Ever greater screen resolutions create long horizontal lines that are hard to look at. The readability of limited width is demonstrated on this very nice Disqus forum we’re on.


#20

I know this is obviously subjective, but I actually like the ‘/’ keyboard shortcut to initiate a search. #1, it doesn’t hijack anyone’s search command, and #2, it’s fairly standard (npmjs.com, atmospherejs.com, Firefox search, etc).