start planning API reference docs

[Rich-Harris]

No description provided.

[codecov-io]

Codecov Report

Merging #2206 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2206   +/-   ##
=======================================
  Coverage   91.83%   91.83%           
=======================================
  Files           1        1           
  Lines          49       49           
=======================================
  Hits           45       45           
  Misses          4        4

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a824a6d...8644473. Read the comment docs.

[Rich-Harris]

Made a bit of progress here. Does this feel like a good structure? Or is the innocently-title 'Markup' section (which is unfinished, note) doing too much work?

https://v3sveltetechnology-igjcquoczp.now.sh/docs

[tomcon]

Yes, feels like a good clean structure to me & not doing too much work (as it stands) @Rich-Harris
Really great work on the docs + superb to see everything coming together and how things are looking.

The tutorial is very good too, only comments so far are, some made by others maybe:

1. The dropdown (when you click on heading in left sidebar) should be more visible and styled
2. Look and feel of the left sidebar is adequate & ok but not quite refined/good-looking enough imo, not sure of what needs to change though (which is not very helpful to you!).

Maybe it's partly colors needing a tweak and/or that there's at least 5 font-families on the go (though to be fair, only Arial can be dropped, the others have good reason why they are used, esp in REPL):

• Overpass for main doc headings, tabs
• Roboto for tutorial main text
• Fira Mono for REPL code
• apple-system, BlinkMacSystemFont, "Segoe UI", for REPL output
• Arial for select dropdown

[Conduitry]

I do think that Markup is probably doing too much work, certainly given that it has no subheadings in the navigation. Maybe it makes sense to split it up at its current level into things like 'directives stuff' and 'brace stuff' but I think better would be to have a third level of navigation that points to each of the existing sections under 'Markup'. I don't know how much work that's going to be, or whether that will then force us to display third-level headings in other sections where we don't want them.

[tomcon]

When you add the missing sections:
TODO classes, actions, transitions, animations, slots, special elements
then yes it would be too much for sure

[Conduitry]

Another easier way forward without having to worry about the navigation would be to have more finely grained anchors for links to specific sections. Each third level section could have its own 'link to this section' thing, without being present in the page navigation.

[Rich-Harris]

I think the markup stuff probably should have its own secondary headings. Even I'm getting lost. I think we can hack together a way of distinguishing between headers-that-create-sidebar-links and those that don't — e.g. #### means '<h4> with a link' and ##### means '<h4> without a link (but still deep-linkable)' or something.

[fiskgrodan]

Looks great imo.

A minor detail is that the alignment on large high resolution monitors gets a bit skewed to the right for me.
A possible change could be this:

@media (min-width: 1200px)
.content.svelte-17wzbqn {
    width: 80rem;
-   padding-left: calc(50vw - 32rem);
+   padding-left: 32rem;
    box-sizing: content-box;
}

[pngwn]

This is nice but it isn't what I expected from an API reference. This will be the goto resource for those more experienced with svelte and for those who wish to see the interfaces of the API they are working with.

Right now, I'm actually a little confused as to what it is for, it feels a little tutorial-ish/guide-ish. I expect all of the information up front in an API Ref, not a gradual breakdown of the interface. I consider it more of a technical document (not that I think it should be confusing or inaccessible for newcomers).

Take the each block section as an example. The API is gradually revealed: first the basics, then indexes, then keys. I really want to see the signature at the very top:

{#each items as item, index (key)}

Then a very simple break down of what items, item, index and key are. Then maybe some further explanation/ examples.

I would expect directives to work similarly, for actions I would hope to see the directive signature:

use:action_name="{parameters}"

The accompanying function signature:

action_name(node, parameters) => { update: Function, destroy: Function }

(or something).

And then a break down of what node, parameters and the returned object and its methods are/do. Then maybe a simple example.

Right now it feels like a simpler version of the guide (but with more information on the actual API), I was hoping for something that was easier to reference.

Maybe I am not understanding the goal of this document.

[fiskgrodan]

I think the Vue API docs has a good structure: https://vuejs.org/v2/api/
It has concise and technical explanations of functions, properties etc of the syntax.

For more detailed beginner friendly explanations of concepts etc there is the guide: https://vuejs.org/v2/guide/

[pngwn]

I certainly wouldn't hold Vue's API Reference as the gold standard but they do a reasonable job of displaying the technical details with links to more in-depth resources. I still think examples belong in API References.

The Stripe Api Ref is good. Stripe has a complex API and they fit in explanations, technical references, examples. Obviously their docs are also huge and backed by a billion dollar company but the format works.

I'm not suggesting we remove the in-depth explanations, just more of a reordering.

[Rich-Harris]

Right now, I'm actually a little confused as to what it is for, it feels a little tutorial-ish/guide-ish

Basically I wanted to avoid ending up with a teetering pile of gibberish like this.

The Stripe example is interesting, I hadn't considered that possibility. My fear with things like

use:action_name="{parameters}"

and

action_name(node, parameters) => { update: Function, destroy: Function }

is that without context it's really a bit meaningless, but — as you say — you don't want to get too deep into the whys and hows in a reference like this. Stripe's reference-on-the-left, examples-on-the-right could be a good alternative.

(It recalls the annotated source for Underscore and Backbone, kind of. Which I was a big fan of.)

I know everyone cites the Vue docs as a reason for Vue's success but I'm not a big fan. Back in 2013 and 2014 they were great, but as the API has grown over the years I frankly find them a bit confusing, and don't really want to emulate them. The one thing I do like is that it links back to the guide (tutorial in our case) which is a good idea worth stealing.

[pngwn]

If you need more examples of bad docs then rxjs is up there with the worst.

I'm not sure about things being meaningless without context. I think at least half of the time when I'm using an API Ref for anything, I've usually just forgotten the signature, or the return value. I know what the thing does, I've just forgotten how to use it. It is entirely possible that I'm not the target audience for these docs (or other docs, who knows).

But I agree, we don't want a mess of interfaces like some API Refs have, they are worse than none at all.

[Rich-Harris]

Playing around with a Stripe-ish layout:

Maybe it frees the copy up to be a bit more referencey and less exampley?

[tivac]

That looks great, and a huge 👍 on making it "more referencey".

[mindrones]

Very happy to see this happening, thanks!

I too got a bit surprised by the guide-like approach.
For things like script, style and markup it's kinda inevitable but definitely I'd use secondary headings, scrolling long texts is hard on the eyes and time consuming, Cmd-F makes you jump on places maybe too far from where you were reading and assumes you know the term you're looking for, so a fast navigation is essential IMO to make the docs quick to consume.

I also would want to see signature and return type, similar to lodash docs: maybe typedoc would help here?

As for the examples I'd love to see svelte-scroller used here, so that text and code are always in sync and visible when needed, I think it'd be a great use case for it.

[mindrones]

I forgot, versioning is important for the reference. You want to know when things got introduced, changed and deprecated.

Regarding examples:

• it would be nice to link REPL examples,
• even better it would be super embedding examples like in the current frontpage (especially in combination with svelte-scroller).

[pngwn]

This looks great, it opens up the page and (hopefully) gives more space for some referencey stuff.

I appreciate this is more difficult for svelte: language as API and a lack of explicit namespaces, in the traditional sense, makes organising an API Reference much more difficult.

I shall hold out hope for signatures, I'm personally not a huge fan of the lodash docs (I like the principle but find them confusing). The best API References with function signatures front-and-centre that I've seen are things like hackage (although the hackage docs in general are horrific) and elm packages.

These are both pure, functional languages, and that is function signature documentation on easy-mode. Javascript doesn't quite have that elegance. But MDN does a reasonable job of giving you information about params and return values and it is a format that people are familiar with, maybe something in that vein would be appropriate (although I'm not a fan of thier optional parameter notation).

Oh, and versioning would be cool but I don't think there is any need to go crazy. A simple introduced in 3.x would suffice from my PoV.

I don't really want REPLs in the API Ref, it slows down the page and we don't need to be cuddly here, we need to be clear and present the information as efficiently (and as quickly) as possible. I really like the annotated code.

Looks like a big improvement, anyway. I like it very lots. 👍

[Rich-Harris]

I think it's starting to come together — take a look (just not on a small screen, yet): https://v3sveltetechnology-qxmiefmlhm.now.sh/docs

[Rich-Harris]

Made some more progress. I'm not particularly happy with how the client-side component API docs look: https://v3.svelte.technology/docs#client-side-component-api

Brain is too fried to think of ways to improve it though.

Also, are the svelte.compile and svelte.preprocess signatures a little overwhelming? https://v3.svelte.technology/docs#svelte-compile

[pngwn]

Maybe the preprocess and compile signatures could use some tables? they are a little overwhelming right now. It would be easier to scan them with a table or two.

As an example for compile it could become:

svelte.compile(source: string, options: object)

And then a note about options taking the following properties:

property	value	default
format	'esm', 'cjs'	I
name	string	don't
filename	string	know
generate	'dom', 'ssr', false	what
dev	boolean	the
immutable	boolean	defaults
hydratable	boolean	are
legacy	boolean	but
customElement	{ tag: string }, true	they
css	boolean	should
preserveComments	boolean	probably
outputFilename	string	be
cssOutputFilename	string	listed
sveltePath	string	here

[Rich-Harris]

There's clearly more work to be done here, but I keep deploying from the master branch and reverting to the out of date docs like a muppet. So I'm going to merge this and apply any further changes to master