Docs mentioning SFC do not demonstrate an SFC

[mikemaccana]

(moved from sveltejs/svelte#1601)

Current documentation

From https://svelte.technology/guide#understanding-svelte-components

A component is a reusable self-contained block of code that encapsulates markup, styles and behaviours that belong together.
Like Ractive and Vue, Svelte promotes the concept of single-file components: a component is just an .html file. Here's a simple example:

<h1>Hello {name}!</h1>

As only HTML is used in the .html file, this is either not a demonstration of, or a poor demonstration of the concept of including JS, HTML and CSS in a single file.

Additionally, since the file is called .html there is nothing to suggest there should be more inside the file than what is shown, ie, HTML.

Furthermore the component has data that is given to it later, on instatiation.

Suggestion

In the example below, I have avoided the use of obtuse language, tightened the copy and avoided the term 'SFC' as it does not serve a purpose - Svelte components are explained to be in a single file, we do not need a new acronym for this

Understanding Svelte components

Svelte applications are made from one or more components. In Svelte, like other frameworks, a component is a reusable self-contained block of code with HTML, CSS and JS in a single file.

<h1>Hello {name}!</h1>

<script>
	export default {
		data: function(){
			return {
				name: Joe
			}
		}
	}
</script>

<style>
    h1 {
        color: red;
    }
</style>

[mikemaccana]

Copying a comment made earlier: while not all the sections are mandatory - we could certainly have an even more minimal example - the question is how well does it illustrate the concept of a single file component? The purpose of documentation is to explain things to users, not to be ultra optimised.

[Rich-Harris]

Thanks. I suppose the intention was to indicate that <style> and <script> are optional. A lot of components just don't need them.

The point about not having default data is deliberate — the next code block, 100px later, shows an example of the component being imported and instantiated with { name: 'world' }. The idea is to quickly build an understanding about what the component is and how you can interact with it in your app.

I'm not sure that including CSS and JS serve that purpose — a newcomer would rightly wonder what happens to that CSS (is it global? scoped? how do I get it into my app?), and until we've introduced the concept of behaviours, someone would reasonably think that the exported literal was the component, which would make the new App(...) section immediately afterwards look very odd.

'Single-file components' isn't a term we invented (unless 'we' includes Ractive!) — it's in very wide usage in the Vue community, for example, and I've seen lots of people talk about SFCs in the context of UI frameworks on Twitter, Reddit, HN etc. It might not be universally understood, but it's helpful to have a name for the concept, and we may as well use the one that is already in use.

[mikemaccana]

I - and I suspect many other developers - tend to just read the code (often because documentation for open source projects tend to waffle). Right now it looks liek you import some .html into JavaScript somehow. The idea that that HTML in the code is a component that doesn't need any styles or behavior isn't obvious from reading the code.

The docs:

A component is a reusable self-contained block of code that encapsulates markup, styles and behaviours that belong together.

The previous comment:

I'm not sure that including CSS and JS serve that purpose

The point - according to the previous sentence in the existing documentation - is you can have structure, presentation and behavior a component in one file. How does showing structure, presentation and behavior in one file not illustrate this?

Yes, CSS scoping should be explained later. But that's OK. The point has been conveyed.

'Single-file components' isn't a term we invented

I know. Just using acronyms doesn't help and makes things worse. Just say 'single-file components' or (better yet) 'components', which are mode widely used than 'SFC'. We don't need more acronyms. Words are fine.

[Rich-Harris]

I know. Just using acronyms doesn't help and makes things worse. Just say 'single-file components' or 'components', which are mode widely used than 'SFC'. We don't need more acronyms. Words are fine.

Where in the docs do we use the acronym?

[mikemaccana]

I'm not sure, first time I saw it was your SO answer, maybe you don't use the acronym at all. I still don't think it's necessary to focus so much on terminology for new users ('single-file components' in italics), hence including the tighter copy above.

Note just giving these suggestions after spending a couple of days trying to get something working - they're written from the wisdom of ignorance: I know very little about Svelte so the gaps between the docs and what I learn from asking questions is very apparent.