General Documentation Work

[nemo-omen]

Hi everyone!

I had a brief Twitter exchange with @wooorm yesterday about improving the documentation for unified and the projects in the collective. The documents at https://unifiedjs.com/learn/ are a great improvement over the READMEs spread across the vast array of utils, plugins, etc that make up unified, but having a cohesive set of docs for the main site would be a great help to newcomers.

In that spirit, I'd like to start a discussion about working on the documentation as a project unto itself and offer to help as much as my time allows.

I'm a computer science student who works in local news full-time and would love to help contribute what I can to this vast ecosystem of tools. My limited understanding may help write introductory documentation that helps people who need a basic understanding of the tools.

Let me know what you think!

[ChristianMurphy]

Welcome @nemo-omen! 👋

yesterday about improving the documentation for unified and the projects in the collective
In that spirit, I'd like to start a discussion about working on the documentation

Improvements to the documentation and new guides are welcome!

as a project unto itself

Do you mean this in the broad context of contributing? Or do you have a more specific meaning to "project" in mind?

help write introductory documentation that helps people who need a basic understanding of the tools.

A fresh set of perspectives, views, and eyes to author and review guides are welcome!

If you have some ideas in mind, would be happy to hear more and discuss!
If you don't and are looking for some ideas to get started, there are some in unifiedjs/unifiedjs.github.io#7 which could be good starting points.

[nemo-omen]

Do you mean this in the broad context of contributing? Or do you have a more specific meaning to "project" in mind?

At the moment I mean in the broad context. My own time is limited but I'd like to start helping where I can.

A set of libraries as large as unified will eventually need some sort of coordinated effort at organizing documentation, though.

Before getting started I just wanted to find out how documentation is coordinated and how I would find where the work is needed.

[wooorm]

I think the main problem unified has, documentation wise, isn’t that stuff isn’t documented: everything is already documented somewhere. I think the main problem is that it’s hard to find.

And an aspect of unified, is that I don’t see it every becoming easy to get into. unified is about 80 times the size of linux, focussing on complex topics (ASTs, compilers), and is very few people with very limited funding.

I’m also somewhat conflicted about users who, for example, want to use unified for one single relatively simple use case such as adding a table of contents to their readme, to name something random. unified is capable of doing that, but that’s like buying a fancy 111 piece hand tool set but then only ever using the hammer. Perhaps those users can be converted to let unified handle more work, and I sometimes do create recipes such as HTML and remark and Tables in remark for them.

---

That being said, there’s a lot that can be improved. I appreciate you wanting to help and thanks for creating this discussions.
My recommendation would be to try and keep it simple. It’s an impossible feat to rewrite all the docs. One guide at a time.

---

Before getting started I just wanted to find out how documentation is coordinated and how I would find where the work is needed.

I guess there are three ways:

• Typically through ideas by people like you.
• questions (that perhaps come up several times) are sometimes turned into guides/recipes (e.g., the tables in remark, and remark to HTML ones; Christian recently contributed several TS guides: Add TypeScript guide and recipes unifiedjs.github.io#37)
• Generally though, everyone’s pressed for time and I’m rather prolific.
  • So for one example, the last weeks I’ve been rewriting the website for MDX (https://v2.mdxjs.com), which is a somewhat small and scoped project making it a bit easier to document. There I’m just working hard to get it in a good place and then asking folks to review top to bottom
  • I want to add “What is this?” and “When should I use this?” sections to all readmes (example: https://github.com/mdx-js/mdx/tree/main/packages/rollup#what-is-this). This means going through hundreds of projects and such work going through everything takes about a month

[nemo-omen]

And an aspect of unified, is that I don’t see it every becoming easy to get into. unified is about 80 times the size of linux, focussing on complex topics (ASTs, compilers), and is very few people with very limited funding.

Yes, the more I get acquainted with the breadth of unified the more I was reminded of D3 — also kind of a challenge to get into because it's a sprawling collection of utilities. The documentation's there, it's just difficult to find your way!

It’s an impossible feat to rewrite all the docs. One guide at a time.

It seems like the main challenge is to find a way to guide new users through learning how to find the tool they need more than re-documenting each one. It could also be helpful to create a very simple introduction that walks through a birds-eye-view of unified and includes examples of how to use each of the major libraries in the collective.

want to add “What is this?” and “When should I use this?” sections to all readmes (example: https://github.com/mdx-js/mdx/tree/main/packages/rollup#what-is-this). This means going through hundreds of projects and such work going through everything takes about a month

I'd love to help with that, although I would probably be much slower making progress than someone who has a better acquaintance with the tools and how to use them. I don't want to take away from anyone else's time by asking to have my hand held through each library.

I was thinking it might help to gather all of the readmes into a single collection but I think that's sort of covered by each entry in the "explore" section. It might just be a matter of organizing the information that's already there.

[wooorm]

It could also be helpful to create a very simple introduction that walks through a birds-eye-view of unified and includes examples of how to use each of the major libraries in the collective.

👍

I'd love to help with that […] I don't want to take away from anyone else's time by asking to have my hand held through each library.

What if we go through them together, in batches. As in, I create 10-20 PRs to add them to certain projects and then we discuss wording? And when ready we do the next “slice”?
Typically I go bottom-to-top (from micromark/syntax-tree, then unified/vfile, then finally remark/rehype/etc). Maybe this time it’s better to go the other direction, which might work better as both you and other users will probably have a better understanding of everything the lower they go?

[nemo-omen]

That would be fantastic! It would be a great way to get a better understanding of how things work together.

[wooorm]

I’ve started working through these btw (example: remarkjs/remark-github#33). If anyone wants to help read through these things, do let me know and I’ll ping you on these PRs!

[mgan59]

👀 -- getting caught up