Documentation: hard to get started for a newcomer - provide simple example(s) in the readme

[marko-knoebl]

As a newcomer it took me some time to get started with this great library. (The first thing I tried to do was transforming a markdown string into an HTML string) I think this could be made much easier if there were some simple code examples in the readme.

A simple example could look like this:

var unified = require("unified");
var remarkParse = require("remark-parse");
var remarkHtml = require("remark-html");

var processor = unified()
  .use(remarkParse) // parses a markdown string
  .use(remarkHtml); // transforms parsed markdown to an HTML string

processor.process("## Hello world!").then(result => {
  console.log(String(result)); // logs: <h2>Hello world!</h2>
});

My impression of the documentation was that it was both hard to find / too spread out and it started off too complex.

If this proposal makes sense I'd be happy to create a pull request and work on the documentation some more in other areas as well.

[wooorm]

Hi Marko, welcome, glad to have you here!

Yes, remark and unified is hard to get into, I think we can’t change that: it does a lot, and it’s different, so it’s hard to wrap your head around. Similar to other hard things in life, you’ll have to read up and practice a bit.

That does not mean we can’t make it easier though, and I think we should do that! So having examples is good. Your example is perfectly fine, except that I think it’s a relatively uninteresting example: there are other projects that can parse Markdown and make it into HTML, remark can do that sure, but it can do so much more! If we’d just show one example, this example, I feel like we’d narrow remark and unified down too much.

I personally think (and have heard from others) that the unified readme, and the unified guides are really helpful. Giving those a thorough read should give newcomers a good understanding.
Those two are already the first two bullet points in the into though!

What do you think?

[marko-knoebl]

Hey, thanks for your reply!

When reading much of the remark / unified resources it feels to me like they're either:

• showcasing the great things unified can do
• taking a deep dive into the internals of unified

I think when I first came to the remark website after just reading a few sentences I was pretty sure: this is just the tool I need and I was excited to get started. However, actually getting started turned out not to be as easy as I hoped.

Your example is perfectly fine, except that I think it’s a relatively uninteresting example: there are other projects that can parse Markdown and make it into HTML, remark can do that sure, but it can do so much more!

This may be specific to me but at this point I was already excited and I wasn't really looking for interesting examples. What I would have liked at that moment was a step-by-step introduction of the fundamentals (even if they are boring) - my initial goal was to try and turn a markdown string into an HTML string. I think I first went to unifiedjs.com which also looked like a mix of showcasing and deep dives. Afterwards I tried the basic tutorial, but that also went in a different direction than what I needed pretty soon. After checking the link to remark-parse I finally went to unified's GitHub page and was able to gather what I still needed from the single code example on the page.

This experience made me try for another option, markdown-it, which started off with really simple examples before diving deeper. Luckily I gave remark another try because it has turned out to be a great library!

Do you think it would make sense to include various examples in the readme? I'd be happy to write up some. Or would it make sense to extend the readme of unified?

[Murderlon]

Thanks, for the issue @marko-knoebl. I'll follow up a bit.

Do you think it would make sense to include various examples in the readme? I'd be happy to write up some. Or would it make sense to extend the readme of unified?

We are currently still figuring out the approach for that! Initial thoughts and work can be found in the guides issue and the handbook repository.

As unified is modular it has many repositories and therefor many possible entry points for users. Ideally, they should link to a single place where you can figure out what you need to know. I'm grateful you like to work on extra examples, but as that place is still in the making, I'm not sure it makes sense to add extra examples in a single place right now. And as @wooorm pointed out, they can already be found in some places.

[marko-knoebl]

I think you're right, there should be a single place to get started with unified. My suggestion of having simple examples in the remark readme is probably not the best solution.

I still stink the experience for newcomers can be improved. Maybe I'll look into contributing to the unified documentation directly.

For now, feel free to close this issue.

[ChristianMurphy]

@marko-knoebl the new https://unifiedjs.com site is live, and includes tutorials centralized in one place.