nodejs
Create templates for content pages
Summary
tl;dr; We can improve the consistency and quality of content by creating templates/guidelines for concepts and tasks, and then applying those to all existing docs pages.
I think that we could improve the quality and consistency of the content on the site by developing one or two templates, and then applying those templates to every page. Similar to the template that I was presented with when creating this issue. First you have to choose an issue type, then you're presented with a suggested template.
This referrers to the content as it currently exists on https://nodejs.dev/. It's a little unclear from the issue queue what additional content might be added to this site in the future.
Motivation
There's a lot of benefits to using a template for both writers, and learners, including:
- Helps keep quality consistent, while reducing bike shedding over formatting
- Makes pages easier to scan, readers know where to look
- Reduces the mental investment required for users to get to, and digest, the most important parts of the page
- It's easier for people to add new pages when there's a template to follow rather than starting with a blank slate
- Improves the peer review process similar to how having agreed upon coding standards helps with code review. You can focus on substance and not nit-picking formatting, etc.
Off hand I know of two other projects that I think are doing a really good job of this. The Drupal 8 User Guide and the Gatsby documentation. In both cases the content is high-quality and recognized as such by their respective communities.
- https://www.drupal.org/docs/user_guide_guidelines/index.html
- https://www.gatsbyjs.org/contributing/docs-templates/
There are more, and if you know of additional examples please share them!
Basic example
Looking at the existing content I think that we probably have two different types of content that we're dealing with. And that breaking the content up depending on which of these two it is also helps with consistency and properly setting expectations for readers. This is based loosely on the DITA Concept, and Task types. And my experience working on Drupal's documentation.
Totally open to other ideas!
Concepts
Answer "What is ..." style questions. These provide background information that helps readers understand essential information. Concepts give context to the information you're learning; Why is this important? When/where will you use this?
Examples:
Tasks
Answer "How do I ..." style questions. They provide step by step instructions for how to perform a specific task or action. They contain a clear goal that the reader is working towards, and a well-defined path to achieve that goal. Often in the form of a set of sequential steps.
Examples:
- https://nodejs.dev/how-to-install-nodejs
- https://nodejs.dev/how-to-read-environment-variables-from-nodejs
- https://nodejs.dev/uninstalling-npm-packages
I think that in a few cases existing pages which cover numerous tasks on the same page would benefit from being broken up into multiple pages. This makes them easier to find when scanning a list, and reduces the amount of extra that someone has to sift through to get to the part they came for.
As an example https://nodejs.dev/an-introduction-to-the-npm-package-manager - this explains a little about what npm is, and also provides some examples of doing basic tasks with it. Having these combined makes it harder for someone looking for "now to install a package with npm" to find this as it's not super clear from the title "An introduction to the npm package manager" that it would be here. Splitting this into two or more pages would help with findability.
In addition to identifying two types of page, concept vs. task, having a template for each that provides a basic structure to follow would help.
As a starting point I think the template should include the following:
- Introduction: Including a brief summary, a bullet list of 2-3 main topics in the tutorial, and a goal statement.
- Body: The meat of the tutorial. Step by step instructions, or an explanation of concepts, illustrations, video, etc.
- Conclusion: A short recap that reminds people what the 2-3 main takeaways are for the tutorial. Followed by a list of 2-3 thought provoking questions intended to encourage readers to further explore the topic on their own. Finally, point people to the next topic they should go to.
A lot of this is based on common instructional design best-practices such as; set clear learning objectives, make navigation simple and easy, promote active learning, etc.
Cribbing from the Drupal User Guide as again that's what I have the most familiarity with here's my proposal for a template:
# Document Title
Short summary, one paragraph. Someone should be able to read this, and the following bullet list, and know if they want to proceed with the rest of the page or not.
Maybe bullet list in "students will be able to" format, e.g.:
- Use npm to install one or more packages
- Install a specific version of a package
- Find addional help for the npm install command
## Goal
State the thing that someone will be able to do once they've completed this tutorial in one sentence using active voice.
## Prerequisite knowledge
- Bullet list of any prerequistes
- Preferrably with links
Main body goes here ... hopefully with some consistent formatting for step by step instructions.
## Recap
Summarize what was just covered in one paragraph.
## Expand your knowledge
Bullet list of 1-3 thought provoking questions intended to help someone further their understanding of the topic they just learned.
## Additional resources
Links to additional useful resources from around the web related to this topic.
Next steps
I think that if we want to proceed with this idea the next steps are:
- Agree on a template(s). Is this a matter of building consensus? Or does it require specific individuals to sign-off?
- Document that system
- Apply that system to the existing content (this is a great task for sprinting once the above items are in place)
Can I suggest we group together content-related threads and maybe hold a dedicated meeting to align.
Unless I am mistaken, this along with discussions around #359, possibly others, all can be benefit a regroup on content things.
Thoughts?
Sure. I'm not very familiar with the current state of this project, or the process for proposing things like this so I'm happy to do what I can to help move the conversation forward.
@eojthebrave We chatted about this in the meeting https://github.com/nodejs/nodejs.dev/issues/395 today and we gave it an enthusiastic 👍 for using templates for improving the content.
If you want to PR in some templates, they can be discussed and maybe have the submission guidelines updated to encourage people to use them.
Also, if you have time to PR in updates to existing content feel free, any PRs that improve existing content are welcome. If you're blocked currently, or in the future, please reach out to @nodejs/website-redesign team on github.
@eojthebrave @jonchurch
So let me try to recall this right, we had discussion on issue templates I think… and we did talk a lot about content related aspects, but I think here the context is well-defined that I'm afraid we may want to do it more justice with more discussion… templates in this context are meant to be structural of content, and that is a very intriguing and detailed, I hesitate to think it can be constructive to timebox this in usual meetings.
So does it sound fair to bring it up this week, a little timeboxed primer (@eojthebrave I hope you can drive it), and pick it up in our TBD bi-weekly (tentatively on Saturdays that follow) hackathons or even in a separate meeting.
Those discussions are needed, imho, since markdown is afterall a human friendly proxy for HTML, and taking a moment (or 10) to better grasp the bigger picture means we can really emphasize semantics for the content while minimizing noise and/or redundant metadata… etc.
This all really pays when your templates can be effectively appropriated by the various content authors, ie you do not offer features they never use or neglect ones they are forced to hack in creative yet inconsistent ways.
Hey @SMotaal, thanks for your feedback. And yes, I'm happy to discuss this further as needed. And agree it warrants further discussion and community input. I started a PR thinking it might help to have an example to point to as part of that discussion. Any and all feedback on how to improve it is welcome!
I should be able to join the meeting on Thursday if it's helpful. I'm also happy to continue the discussion here. I'm new to the process of contributing to this project so whatever works best just let me know. That said, Saturday's are hard for me, at least for the next month or so.
I'm not 100% clear on what questions you're asking, or if you have specific thoughts for discussion or just want to talk about this idea more in general?
templates in this context are meant to be structural of content
I think this accurately sums up my goal. Provide consistent structure to the content of documentation pages by specifying a set of headings/sections that should exist on all pages and suggestions for what they should contain, while still leaving ample room for content authors to fill in the main body of the document in whatever way makes the most sense.
Those discussions are needed, imho, since markdown is afterall a human friendly proxy for HTML
Are you suggesting that there may be a better, and more machine friendly way, to structure the documents (e.g. MDX?) than using Markdown? And wanting to figure out what that looks like?
Or are you wanting to have more discussion about what headings/sections we're prescribing for the structure?
Assuming I'm able to join the meeting on Thursday is there anything that you (or anyone else) suggests I do in order to be prepared to help lead the discussion?
@eojthebrave I think it helps to just go over the issue with everyone on Thursday, this way we get everyone on the same page and allow folks to give input or opt to helping with next steps.
Apologies, I too am fairly new to the project, and somewhat so on multiplayer GitHub :)
If you don’t mind, I’d like to think about your reply and address it in the meeting... I’m still trying to find good ways to avoid my making too much noise replying in threads.
So let’s see what Thursday brings, fair?
So thank you so much @eojthebrave for bringing this up along with your expertise across the various content-oriented open source efforts.
Aside — I'll just add some context, I am on a long and tangentially related journey troubleshooting accessibility disconnects (my own and others) which are almost impossible to define and hammer at with conventional framing of
a11y— this is absolutely diversity, but it sadly as far as collaboration goes, this inadvertently fostered silos around similarities, ie exclusive inclusion, because of the gaps in the frames of reference that make it impossible for folks to be observing their "fair-share" of burdens of mutual differences, only discomforted with a "thin slice" frustration of the same not working as expected with one or few (some sadly say "it is on the messenger to…" even, which is displacing their anger in far more offensive ways when the mutual chore was communicating).So this week it was all falling in place for me, removing the friction in documentation is the first step for inclusivity that is not also unintentionally exclusive, ie the step towards true inclusion, and I tried to not miscommunicate when I described it in Frictionless Documentation.
To make documentation semantic, it means it can be interpolated, even extrapolated, and we don't need to know why or how yet, just that it can be, logically… and your structural templating angle is absolutely spot on here, thank you!
Hey @SMotaal thanks for sharing, I've read your post and the linked documents. And, I agree that accessibility is an important thing for us to consider when creating documentation. I took two things away from it:
- We should ensure that our templates can be parsed by machines in order to extract the different pieces. e.g.) summary, in a meaningful way
- Based on the "Inclusive Meetings" documents you linked in your post we need to make sure that our style guide (#282) includes information that helps ensure we write documentation in an accessible way. This is less about machines being able to parse it, and more about making sure that for example we don't use words like "just, easy, or simple", and avoid using gendered language.
Follow up from Nodejs.dev collaborators meeting
I joined the last contributor call, and there were some questions that need to be addressed before we move one. The biggest one is making sure we take the time to ensure that whatever we put into the tutorial Markdown files can be parsed/processed into the meta-data, and HTML structure, that we want to provide.
So, first lets look at what data we want, and what that might look like as HTML in an ideal situation.
I think we should be able to extract the following from a tutorial Markdown file or otherwise infer at build time. This can be provided through some combination of frontmatter, and HTML tags in the document:
- Title
- URL
- Last modification date
- Author(s)
- Summary
- Complete Text
- Set of steps for step-by-step tutorials
- Applicable Version(s) of Node.js: Potentially useful to track this?
Here's what I think the HTML document we render should look like.
MDN documentation recommends the use of an <article> tag to contain portions of the page that stand along as a document. So we should wrap each tutorial in an <article> tag.
And, the recommendation is to use <article> tags inside of an <article> tag to further subdivide the content. If that sub-content makes sense to syndicate as it's own standalone piece. With regards to a tutorial, I thinks is probably true for the summary of the tutorial, which we may want to syndicate and use as a teaser elsewhere. For the other sections, body, and conclusion, these likely are not useful on their own, and so we should instead use a <section> tag to denote them.
Implement table of contents for the document as a <nav> element. If inside the <article> tag it relates the navigation to the sectioning element and makes these links semantically tied to the tutorial content. Note that this is automatically generated and inserted, and not something the content author needs to worry about creating.
Implement links at the bottom of a tutorial that point to related content, and the follow-up questions as a <footer>. According to the docs, "A footer typically contains information about the author of the section, copyright data or links to related documents." And relates it to the nearest sectioning element. The <article> tag in this case.
<article class="tutorial task-tutorial">
<header>
<h1>Tutorial title</h1>
Other meta-data like author, and modification date ...
</header>
<nav>TOC</nav>
<article class="tutorial-summary">
<h2>Summary</h2>
<p>Article summary</p>
<ul>...
<p>...
</article>
<section class="tutorial-goal">
<h2>Goal</h2>
<p>The goal of this tutorial ...</p>
</section>
<section class="tutorial-body">
<p>Fill this with the body of the tutorial</p>
<h2>Sub-headings h2-h6 as appropriate</h2>
<pre><code>Code samples</code></pre>
<p>Basically ... whatever HTML is generated from the Markdown ...</p>
</section>
<section class="tutorial-conclusion">
<h2>Conclusion</h2>
<p>Recap of the tutorial ...</p>
</section>
<footer class="tutorial-footer">
<h2>Further your understanding:</h2>
<ul>
<li>Question one.</li>
</ul>
<h2>Additional resources:</h2>
<ul>
<li><a href="">Link to related article</a></li>
</ul>
</footer>
</article>
Here's a proposed markdown structure that could be used to replicate the above, and provide the meta-data we need:
---
title: Tutorial title
authors: @author1, @author2
section: Quick Start
---
<article class="tutorial-summary">
## Summary
Article summary ...
- List of items
- List item two
</article>
<section class="tutorial-goal">
## Goal
The goal of this tutorial is ...
</section>
<section class="tutorial-body">
Fill this with the body of the tutorial
## Sub-headings h2-h6 as appropriate
\```js
console.log('hi');
\```
Basically ... whatever we want to include in the tutorial.
</section>
<section class="tutorial-conclusion">
## Conclusion
Recap of the tutorial ...
</section>
<footer class="tutorial-footer">
## Further your understanding:</h2>
- Question one
- Another question
## Additional resources:
- [Link to related article](https://example.com)
- [Link to that one other article](https://example.com)
</footer>
Using a Markdown file structured like the one above we should be able to replicate the example HTML markup. The path, and last modified date should be able to be computed at build time. And we can parse the summary out with the <article class="tutorial-summary"> ... </article> tags.
We could also add rules to the remark-lint tooling to validate that all the required sections exist.
Reviewing information from Schema.org, my recommendation is to use the https://schema.org/Article type for concept style tutorials, and the https://schema.org/HowTo type for task tutorials. HowTo provides the ability to designate a HowToStep, and HowToDescription, so if the task tutorial provides sequential step-by-step instructions we could use this. It would mean adding something to the Markdown mark to ensure we could parse out the individual steps. Probably by deciding now on what the HTML structure looks like.
This could look something like the following:
<section class="tutorial-body">
Fill this with the body of the tutorial
## Here's a set of steps
<div class="steps">
<div class="step">
### Step heading
Content of the step
</div>
<div class="step">
### Step heading
Content of another step
</div>
</div>
</section>
My thoughts on this are that it would be nice to have this structure as it would allow for CSS targeted at steps that improve the visual appearance. And, we could parse this into the JSON-ld structure of a HowTo document. However, I also think that this could potentially introduce undue burden on content creators. And we would need to make sure that the HTML structure we want to see is clearly documented, and that it's easy to find copy/paste examples.
Another alternative would be to use MDX (Markdown + React), and create custom components that we can use in these tutorials. This might make the Markdown file easier to read. Custom components are potentially more self-documenting than HTML tags with specific class names. And, would give us the flexibility to more easily modify what the rendered HTML looks like later as we can change what the components output.
Example of what the above might look like using MDX:
---
title: Tutorial title
authors: @author1, @author2
section: Quick Start
---
<Summary>
Article summary ...
- List of items
- List item two
</Summary>
<Goal>
The goal of this tutorial is ...
</Goal>
<Body>
Fill this with the body of the tutorial
## Sub-headings h2-h6 as appropriate
\```js
console.log("hi");
\```
Basically ... whatever we want to include in the tutorial.
<Steps>
<Steps.Step>
<Steps.StepHeading>Step heading</Steps.StepHeading>
<Steps.StepDescription>
And then output the result with:
\```js
alert('hi');
\```
</Steps.StepDescription>
</Steps.Step>
</Steps>
</Body>
<Conclusion>
Recap of the tutorial ...
</Conclusion>
<Footer>
<Footer.Further>
- Question one
- Another question
</Footer.Further>
<Footer.Additional>
- [Link to related article](https://example.com)
- [Link to that one other article](https://example.com)
</Footer.Additional>
</Footer>
Given all of this, I think my recommendation would be to use MDX, with the caveat that I've never personally used it before so am not familiar with what the downsides might be.
@eojthebrave I'm going to be giving this full 👀 today… but the gist of it looks amazing and very thorough, thank you.
I'll post separate comments on key points as I go through this!
MDX — I think MDX has its crowd and merit for certain uses, but imho it is one step out in the opposite direction, it forces our pipeline to become non-conforming even before we start, ie editing, tooling… etc.
Custom Elements — Since want to go route of <…> then maybe we can consider <article-something> or <section-something> which would be HTMLElement and presenting more like <div> which can be styled without .class — since this is all structural, we do not want to think of them as components, ie we do not expect them to be customElements.define(…) to fulfill their function.
👍 I'd personally opt for Custom Elements, I have played around with them long enough for both structure and components.
Headings — This has long been a struggle to find good reason with, but with <article>, <section>, <header>… etc, we effectively see the cascade of things and run into the fundamental question of separation of concerns.
So if we see this:
<article …>
# Article Title
<section …>
# Section Title <!-- bad idea… hold on… -->
We know Section Title is <h2> since Article Title is <h1> and we verbosely have this:
<article …>
# Article Title
<section …>
## Section Title
Now we could say, if we see this:
<article …>
# Article Title
## Heading A
…
## Heading B
We verbosely have this:
<article …>
# Article Title
<section>
## Heading A
…
</section><section>
## Heading B
Now back to the first bit, we're more likely to be dealing with:
<article …>
# Article A
## Section A.1 <!-- nice -->
### Subsection A.1.a <!-- nicer -->
### Subsection A.1.b <!-- nicer yet -->
…
## Section A.2 <!-- just works -->
And this transitively would be:
<article …>
# Article A
<section>
<article>
## Section A.1 <!-- nice -->
<section>
### Subsection A.1.a <!-- nicer -->
</section>
<section>
### Subsection A.1.b <!-- nicer yet -->
…
</section>
</article>
</section>
<section>
## Section A.2 <!-- just works -->
</section>
</article>
-
It feels good to not ask authors to think of the final
h-levelWe can also consider
<hgroup>for typographic leveling — likehgroup > h1 + h2. -
It feels good to not ask authors to be too verbose
We can also consider
<meta>tags semantically if we want — instead of<section …>which would be confusing for authors. -
It feels good to not ask authors to determine semantics
We can now infer things like
<section name="tutorial-goal">from pure structure — ie why semantic templates was a 🎩 proposal imho.
This is all up in the air obviously, but if we find there is clarity enough to logically define the 3 states then it becomes easy to chip away at the cognitive burdens of authors and developers.
Thank you so much for doing all this work once again @eojthebrave!
🎩
I hereby propose coining thee
frictionless-semantic-templates
courtesy of @eojthebrave and the @nodejs/nodejs-dev folks
working draft
Thanks for taking the time to go through all of this @SMotaal.
I'd personally opt for Custom Elements, I have played around with them long enough for both structure and components.
I've never used Custom Elements before so I'm not very familiar with them. But it seems like this could be a good approach. I do like that it's perhaps clearer to do <section-goal></section-goal> than <section class="tutorial--goal"></section>.
Honestly, as far as technical implementation goes I'm not personally tied to any approach. Standard HTML, MDX, Custom elements .. as long as we can parse the .md file into structured content I think we're in good shape and can have the build process massage the resulting output for styling as needed.
Regarding the suggestions for how to handle headers and header depth, it's not clear to me what you're proposing. Would it be possible for you to re-work one of the examples I posted above to incorporate your suggestions?
Are you saying that if we have a consistent header structure like:
# Title
## Summary
## Goal
## Body
Copy goes here ...
## Body sub-heading
Something more ...
## Conclusion
That we can use the existence of those headings to break the document up into it's relevant sections? And therefore don't need to ask authors to include things like <section-goal> in their writing?
Thinking more about the idea of using known headings as a way to subdivide the document, instead of using something like <section-goal>; It would limit our ability to skip a heading/section on any given page. And at least for some of the proposed sections like "Additional resources", we probably want to allow someone to leave them off. And the template is really more of a suggestion, than a rule.
Maybe though, if some headings are required, and some are optional, we could indicate in the template's documentation which ones are which. So "summary", "goal", and "conclusion" I think should be required in this case. We can then infer "body" as anything starting from the first header after "goal" and ending at "conclusion". And we could infer "footer" as anything after the "conclusion" section. Which could still work to allow for generating the desired HTML markup.
@SMotaal do you feel like your questions have been answered, and/or do you have any remaining questions I can look into? I would love to be able to start spending some time on re-working existing content to fit a template, but that's blocked on us all agreeing on what the template should be.
What else can I do (question to you and anyone else!) to help move this forward?
@eojthebrave I feel we both expressed a lot of good details, and likely addressed our mutual concerns, yes… But just to make sure things are well articulated, I feel inclined to want to connect and discuss this on zoom. Let's connect through slack.
What else can I do (question to you and anyone else!) to help move this forward?
@eojthebrave I think the whole point is to make sure everyone's effort is properly aligned to the collective goals… I hope you can appreciate my attempts to connect everyone here are trying to do that.
I think the whole point is to make sure everyone's effort is properly aligned
Yes! I totally agree. I would rather we have these conversations now and hopefully save ourselves from having to re-do things to much in the future. Not trying to rush anything, rather I just have a bit of time and interest so trying to do whatever I can to make progress.
I'll try and connect with you on Slack sometime later this week. And/or maybe I can try and join one of the zoom meetings again sometime in the near future. I'm a little more open on the weekends now than I was a couple months ago.
Templates are kind of provided already. I am closing this. (If we need anything better, let us know)
