Transpose Deep Dive documents to documents/

[RafaelGSS]

In some past WG Meetings, @gireeshpunathil told me that would be great to transpose some documents created on Deep Dive Meetings (see #439) to the documents/ folder at this repository.

This issue is to clarify this action and revisit some files that have been there.

[RafaelGSS]

@gireeshpunathil Can you provide a better context here?

[gireeshpunathil]

ok.

The purpose is to transform the deep dive document into the structure defined in the documentation folder in the repo https://github.com/nodejs/diagnostics/tree/master/documentation.

The reason why we are doing is, the deev dive content is mostly free flow write-ups came out of discussions in WG sittings, largely for our consumption. That needs to be in a format that is externally consumable.

To know how to do that, let us take an example of https://github.com/nodejs/diagnostics/tree/master/documentation/profiling

• Readme.md should contain a high level overview of what use case this flow is addressing (done)
• setup.md may contain pre-requisites for the system to be able to follow diagnostics (not done)
• investigation_flow.md may contain high level steps on the problem determination (not done)
• case_study.md may contain an investigation of a specific use case with real data (node done)
• step1, step2, .. may contain different tools / methods to solve a problem (not done)

may contain indicates that those documents are not must, only requires if the specific use case requires one (considered on a case basis)
different setps are present only if a problem is solved in different ways (tool1, tool2 etc.)

Hope this helps!

[RafaelGSS]

Excellent.

Probably would be great to check the folders inside documentation/ and provide a clear vision of what we want to expose at each folder. For instance, the cpu and profiling can expose the same thing in some way.

1. How we can deal with this cross-context?
2. What do you think about creating a README inside documentation to explain each topic before dig into it?

I believe that with these clear ways we can create the topics.

[gireeshpunathil]

1. I don't think this happens with every use case / user journey. Let me try to inspect the cpu / profiling cross context and get back on this.

2. Yes, a good idea! (go for it if you like)

[RafaelGSS]

Alright. I've checked the folders inside documentation/ and mostly of steps will redirect to node.js documentation, for instance live_debugging. How diagnostics/docs and nodejs/docs will work together? I mean, we already a lot of documentation regards to diagnostics but it is outside of this repository(nodejs docs) and probably will have duplication with this repository.

[gireeshpunathil]

mostly of steps will redirect to node.js documentation, for instance live_debugging.

I don't think so. The main trunk of the live debugging is expected to be in How to - a detailed guide on doing live and step debugging (which is a TODO at the moment) and has no existing doc in the nodejs/docs as far as I know. Little overlap may be there, but it is fine as long as our docs are coherent, and aligned with the user journey

[github-actions]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.

[RafaelGSS]

I can't revisit it in these weeks. I just add to my backlog and when free I take a look at that. If someone wants to work on this, feel free to re-open.