doc: revamp gc trace documentation

[tony-go]

Hi Diag Fam 👋

Context

I recently wrote down a guide and pushed a PR on the nodejs.org repo.

As discussed in the recent meeting, it was probably not the best approach as we already have a guide in this repo. Also, the main strategy was to write documentation here first, then move it to the nodejs.org repo as a guide.

Update

EDIT: I finally just keep exercises here. The content is available in this PR: nodejs/nodejs.org#4775

[RafaelGSS]

Amazing! I'd just move the changes in using_gc_traces.md to a separate document. Since we have merged that documentation to nodejs.org, we need to remove it from here.

[tony-go]

Thanks for all your suggestions @RafaelGSS 🥰

[tony-go]

Hey @RafaelGSS 👋 I just added a script idea (alternative). Could you please share your thoughts on it?

Note: it's just a script, I didn't update the tutorial atm.

[RafaelGSS]

Sorry to be very strict in this PR 😅

[tony-go]

I integrated the new script into the tutorial @RafaelGSS

Once you'll finish the review. Should I raise a PR on the node repo?

[RafaelGSS]

I'd just move the changes in using_gc_traces.md to a separate document

Well, I still support this opinion... but, I won't block it anymore.

cc: @nodejs/diagnostics

---

I believe there is a typo in exercice, that should be exerciSe.

---

Should I raise a PR on the node repo?

Yes, please

[tony-go]

I'd just move the changes in using_gc_traces.md to a separate document

Maybe I didn't get the purpose properly: "Since we have merged that documentation to nodejs.org, we need to remove it from here." - Could you elaborate a bit?

I mean, I'll delete the file just before the merge and just let the exercise if it was your point. Or maybe It's for readability (during the review)?

[RafaelGSS]

My idea is:

• Create an README.md inside exercise folder
• The file will contain all the steps to perform the exercise
• So, instead of modifying all the existing content inside using_gc_traces.md, you could just include something like:

+ The Diagnostics WG created an exercise that you can practice and improve your gc-tracing skills, check it _here_ (link to the exercise folder)

This way we'll have two kinds of documents, the first one a pure and raw tutorial (using_gc_traces.md) and the second one for beginners (exercise/README.md). Does that make sense to you?

[tony-go]

This way we'll have two kinds of documents, the first one a pure and raw tutorial (using_gc_traces.md) and the second one for beginners (exercise/README.md). Does that make sense to you?

I understand your point but don't understand why the guide should stay pure and raw. When I look at other guides, they seem guided and detailed. Even If I understand the purpose of "pure and raw" I think that is more suited to documentation rather than guides.

Anyway, I could adopt a different approach if we decide to follow that way.

Maybe the team could share his view on this cc @nodejs/diagnostics

[RafaelGSS]

That's fair enough

So, my final review is just:

• Fix the typo exercise
• Perhaps include the ## Examples of diagnosing memory issues with trace option:

Great work!

[RafaelGSS]

Couldn't we use it somehow? The content is pretty good.

[tony-go]

I use them in the body of the guide.

[RafaelGSS]

Please remember to open your changes in the nodejs.org project. The using_gc_traces.md file has been removed from this repository.

[tony-go]

Seems to be ready @RafaelGSS

Maybe should we add a README in the exercice folder ?

[RafaelGSS]

Seems to be ready @RafaelGSS

Maybe should we add a README in the exercice folder ?

Yes, please

[RafaelGSS]

LGTM.

[tony-go]

🎉