Writers guide #197
Writers guide #197
Conversation
There was a problem hiding this comment.
Thanks Will! This is amazingly useful to get us to a common understanding of stumptown-content.
I have a few suggestions but nothing big. I also added some comments to your "Notes", but I kept them short. I think we should file follow-up issues to discuss these matters.
I think I would like to see this split up a bit in the future, so that the writer's guide could talk about stumptown-content infrastructure generally and then about page types and page building blocks more specifically in separate writer's guide md files. Right now, this is of course quite specific to HTML docs, as that is all we have currently, but I think each page type and each page building block could deserve it's own writing guide doc.
| specifications: https://html.spec.whatwg.org/multipage/semantics.html#the-abbr-element | ||
| ``` | ||
|
|
||
| **Note: I don't see a reason why the front matter property includes a scheme, but the scheme is not present in "specifications.yaml".** |
There was a problem hiding this comment.
We can add it. I have no strong opinion about it. :)
| [SphinxKnight](/en-US/profiles/SphinxKnight) | ||
| ``` | ||
|
|
||
| **Note: this is the most hacky and least acceptable piece of stumptown. In particular, I think that legacy contributor information should not live in /content, because it is read-only: authors should never need to be aware of it. But this is only one of its problems.** |
There was a problem hiding this comment.
I agree! Maybe it should scrape into /legacy/* with a bunch of other read-only things we will need to have to preserve history?
Co-Authored-By: Florian Scholz <[email protected]>
|
|
||
| ``` | ||
|
|
||
| Heading names are mapped to identifiers by being lowercased and having spaces converted to underscores. So we can see here that the `<br>` docs include all the three mandatory prose sections, and none of the optional sections. |
There was a problem hiding this comment.
It'd be nice to mention "slugs" here since we use that in the code
| Each example is specified as a directory containing four files, one mandatory and three optional: | ||
|
|
||
| - "description.md" - the only mandatory one | ||
| - "example.html" |
There was a problem hiding this comment.
What if you need multiple chunks of a given code type? Like two HTML chunks so you can show a piece of code, explain it, then add another piece of code? Same goes for JS and CSS. Actually, JavaScript is where this gets used most. I find it very useful to be able to break up the JavaScript in particular and explain it in smaller pieces.
In fact, what I'd really prefer is the ability to embed subsets of a given code file. Here I'm using macro syntax for demonstrative purposes, because I am not yet fully versed in the stumptown mechanisms, but I have always wanted the ability to do something like the following examples:
{{EmbedJS("example.js", {function: "setupWebXR"})}}
(embed the function setupWebXR() from the file example.js)
{{EmbedJS("main.js", [{commentblock: "globals"}, {function: "myApp.startup"}, {function: "myApp.shutdown"}])}}
(embed the code bracketed by matching comments with the word "globals" encoded (maybe like /* embedname: globals */), then the startup() function followed by the shutdown() function from the myApp object)
Similar things for CSS and HTML. Anyway. Just something I always wanted to have. But at least it would be nice to know whether we can have multiple files of each type.
There was a problem hiding this comment.
At the moment I don't intend to support multiple chunks of code with prose interleaving.
I don't think it is worth the complexity. If we do find it's needed, we will look into adding it. In general though I really want stumptown to be a much simpler system than Kuma/KumaScript, and really to justify every bit of complexity we add to it.
I find it very useful to be able to break up the JavaScript in particular and explain it in smaller pieces.
I'd suggest we use code comments for this.
|
|
||
| * "embed-compat": this tells stumptown that the guide wants to embed a BCD table at this point. Its argument is a BCD query string like "html.elements.audio". | ||
|
|
||
| We will probably add support for more directives in future, not too many. One likely candidate would be "embed-link-list". |
There was a problem hiding this comment.
+1 for embed-link-list.
Do we need an embed-media directive to embed a video or audio object in the page? Possibly also embed-youtube or such. I ask because there's nothing in this document about how to embed video.
There was a problem hiding this comment.
How many pages use this? In MDN we have 76 pages (en-US) that use EmbedYoutube. They are almost all in devtools, which won't be in stumptown. So I don't see a current need for this.
|
|
||
| We will probably add support for more directives in future, not too many. One likely candidate would be "embed-link-list". | ||
|
|
||
| Directives can be inserted anywhere in guide pages. They can only be used in guide pages. |
There was a problem hiding this comment.
Why only guide pages? I ask because I strongly suspect we will come to regret that limitation eventually. Especially if it winds up being the mechanism used to embed media files and the like.
There was a problem hiding this comment.
Firstly because it makes everything more complex. Secondly, because it's part of the concept of reference pages that they can be quite formally structured, and letting people put random things like this wherever they like undermines this.
Mostly though, because it really breaks the idea that the content can be easily machine-accessed. At the moment in stumptown, a section of prose is just a section of relatively simple HTML. So it's possible, for example, for a consumer to fetch just the "Accessibility concerns" section of the doc, and display it in the context of an accessibility inspector. But what if this section contains an "embed-compat" directive? Well:
- the JSON output could include the directive, like our ?raw endpoint. Then the consumer has to understand how to process directives.
- the JSON output could include the rendered BCD table. Then stumptown-content is determining how the content ought to be rendered, which we really want to avoid.
- the JSON output could break up "Accessibility concerns" into the prose pieces and the interleaved BCD. This is what we do for guide pages. But then there isn't an "Accessibility concerns" at all.
- ?
I ask because I strongly suspect we will come to regret that limitation eventually.
One advantage stumptown has over Kuma is that Kuma had to anticipate what the likely use cases were going to be. That's really hard and means you necessarily end up building lots of things you don't really need (but then find it hard to remove for various reasons). But stumptown is dealing with a really mature content base. So we know, pretty much, what the use cases are. It doesn't seem very likely that people will start writing radically new types of JS docs at this point.
|
|
||
| **Note: we will need to think about how to extend this grammar for more complex sidebars.** | ||
|
|
||
| **Note: we should probably abandon this "infinite levels of sections" thing here and perhaps restrict ourselves to three levels (by not allowing children to contain children).** |
|
|
||
| A "chapter list" is just a way to provide a reusable list of links to pages, presented in a particular order. For example, a sidebar might want to list all the HTML guide pages in a curated order, with the most basic first, and more advanced concepts later. So the sidebar specification could provide its own list of pages to include. But an HTML landing page might also want to include the same list, in the same order. This is what chapter lists enable you to do. | ||
|
|
||
| A chapter list is a YAML file with the following contents: |
There was a problem hiding this comment.
It would be nice if we could have the ability to divide the chapter list up into titled sections, to be rendered like
The basics
- Introducing HTML
- Adding styles
- Showing pictures
Forms and inputs
- Adding forms to pages
- Input type guide
... etc...
There was a problem hiding this comment.
I think we should leave this until and unless we have a definite need for it.
|
@Elchi3 , @ddbeck , @a2sheppy - thanks for all the comments! I should have said this before, but: I think it would help my sanity if you can distinguish comments on the doc from comments on stumptown. I want the doc to describe what stumptown is currently, not what it might aspire to be. Comments of the first sort should potentially prevent me from merging this PR. Comments of the second sort should most likely result in us filing separate issues, maybe after a bit of discussion on this PR. For those we should also perhaps add these little "Note:" bits here, just to remind readers that this is expected to change. |
|
Thanks very much @Elchi3 , @ddbeck , and @a2sheppy for such thoughtful comments! I think I haven't got to all of them yet but will try to tomorrow.
Yes, definitely. Especially the rather more formal specs about the different ingredients should be split out. But for now I also wanted to have a one-stop place for people to start understanding it all, without having to jump around too much. |
|
I'm merging, since it's docs-only and has at least one r+. I think it will do more good in the repo than in a PR. If there are outstanding issues let's file follow-ups. |
Here's a first draft "writers guide".
It's supposed to help orient writers in stumptown, and also go into the details of how the various structures in stumptown are defined.
It should help you understand the authoring interface, and also writing it down should help expose some of the problems and inconsistencies it has, and places we can clean it up. I've added notes like Note: a thing in places where it seems to me we want to change things.
I'm interested in knowing if you think this doc makes sense as an explanation of the "authoring interface", and I also I'm definitely interested in knowing about things in here that surprise or concern you or are just too complicated.