Migrate MAT Content from Eclipse Wiki

[eclipsewebmaster]

| --- | --- |
| Bugzilla Link | 583209 |
| Status | NEW |
| Importance | P3 normal |
| Reported | Apr 29, 2024 10:34 EDT |
| Modified | Apr 29, 2024 10:34 EDT |
| Reporter | Krum Tsvetkov |

Description

Created attachment 289371
MAT Content from Eclipse Wiki

As the Eclipse Wiki is going to be shutdown, we need to move the MAT content from there.

For most of the content, I believe it would be most appropriate to have it into the source repo. However, as we haven't made a detailed plan, I'd for now at least attach here the exported content from the Wiki. I exported everything under Category:Memory Analyzer, following the guide [1]. In there, there are some ways described to convert to different formats.

[1] https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-Move-FAQ

:notepad_spiral: Eclipsepedia-20240429142613.xml

====

• MemoryAnalyzer/Building MAT With Tycho - code repo
• MemoryAnalyzer/Contributor Reference - code repo
• MemoryAnalyzer/Docker - code repo
• MemoryAnalyzer/WSL - code repo
• MemoryAnalyzer - documentation; for end users, most of the content is I believe already in the documentation
• MemoryAnalyzer/Adding a new heap dump format to the Memory Analyzer - code repo
• MemoryAnalyzer/API policy - code repo
• MemoryAnalyzer/Contributor Reference/Website - delete; the web site and code repo are now to projects "next to each other" on github.
• MemoryAnalyzer/Extending Memory Analyzer - code repo
• MemoryAnalyzer/FAQ - documentation; might be worth to have a copy / link on the web site
• MemoryAnalyzer/Indexes - code repo
• MemoryAnalyzer/Learning Material - web site (need to check first how relevant the content still is)
• MemoryAnalyzer/MAT Capabilities - either delete it or update it move it to the code repo;
• MemoryAnalyzer/OQL - documentation (might be already there)
• MemoryAnalyzer/Ramp Down Plan - ??? not sure about this one. Probably web site...
• MemoryAnalyzer/Reading Data from Heap Dumps - code repo
• MemoryAnalyzer/Releases - delete
• MemoryAnalyzer/Retention policy - web site
• MemoryAnalyzer/Shared Installation - - code repo
• MemoryAnalyzer/UI - delete it

[krumts]

I need some feedback on this one. In short - my current feeling is that we don't need a Wiki.
Most of the content we have in the Wiki could either

• be moved into the code repository, as it is targeted for developers working with the MAT code - I'd say we should have a /docs folder in the repo and place all the pages there as .md files
• be moved to documentation or the Web site (as it is targeting end-users working with the tool)

There are only a few pieces, which can't easily classify - e.g. the ramp-down plan, which was a requirement for the SimRel participation and neither developers coding against MAT nor end-users would be interested in.

Below I listed all 20 pages we have and added my view on what we should do with each of them. Please give me some feedback on:

• do you agree don't need to maintain Wiki
• the proposed action for the pages

MemoryAnalyzer - documentation; for end users, most of the content is I believe already in the documentation
[MemoryAnalyzer/Adding a new heap dump format to the Memory Analyzer] - (https://wiki.eclipse.org/MemoryAnalyzer/Adding_a_new_heap_dump_format_to_the_Memory_Analyzer) - code repo
MemoryAnalyzer/API policy - code repo
MemoryAnalyzer/Building MAT With Tycho - code repo
MemoryAnalyzer/Contributor Reference - code repo
MemoryAnalyzer/Contributor Reference/Website - delete; the web site and code repo are now to projects "next to each other" on github.
MemoryAnalyzer/Docker - code repo
MemoryAnalyzer/Extending Memory Analyzer - code repo
MemoryAnalyzer/FAQ - documentation; might be worth to have a copy / link on the web site
MemoryAnalyzer/Indexes - code repo
MemoryAnalyzer/Learning Material - web site (need to check first how relevant the content still is)
MemoryAnalyzer/MAT Capabilities - either delete it or update it move it to the code repo;
MemoryAnalyzer/OQL - documentation (might be already there)
MemoryAnalyzer/Ramp Down Plan - ??? not sure about this one. Probably web site...
MemoryAnalyzer/Reading Data from Heap Dumps - code repo
MemoryAnalyzer/Releases - delete
MemoryAnalyzer/Retention policy - web site
MemoryAnalyzer/Shared Installation - - code repo
MemoryAnalyzer/UI - delete it
MemoryAnalyzer/WSL - code repo

@ajohnson1 @kgibm @jasonk000 WDYT?

[kgibm]

do you agree don't need to maintain Wiki

I agree. There's also a Wiki on GitHub if needed (though I agree it's better to just integrate content into the website, help, or /docs in source): https://github.com/eclipse-mat/mat/wiki

I reviewed the list of pages and your proposed actions and they all seem good to me.

[jasonk000]

I think there's an interesting opportunity / overlap in the JIFA guide -> https://eclipse.github.io/jifa/guide/heap-dump-analysis.html

So, if anything I'd encourage an online wiki or source rather than in-app documentation, since both guides will likely have a lot of overlap.

cc @D-D-H

[krumts]

Thanks for the feedback!

I think with this I can already start moving the contributor guide targeted for developers under /docs in the code repository.

@jasonk000 Thank for the pointer to the JIFA guide!
I fully agree having in-app documentation is way too restrictive. However, the docs are also available online [1] and show up in google search. In there we have the basic tutorial [2] and I think what we have under "Concepts" [3] is the closest to the current JIFA guide structure. I have the feeling, that the parts we have in the wiki (and meant for end-users) are mostly redundant to what we have in the docs, but they deviate over time.

Having said that, I see that although it is linked on the project web site, the MAT documentation still feels "separated" and hidden. In addition, the fact that it is built from XML (with DITA) makes it I way too difficult for anyone to contribute to it.
I think we should consider to improve this. We could for example render the docs also in a different form and put a copy of them directly on our web site, instead of referencing the central Eclipse help. Or what I think would be a better way, but needs more thought and effort - move away from the XML format, have the content in e.g. markdown (consumable directly from the repo / over the web), and then find a way to render them also in whatever format is needed for the eclipse help plugin within the tool. May be a mixture of both

As said, I'll start with moving the contributor docs and let us keep discussing what is best for the other docs.

[1] https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.mat.ui.help/welcome.html
[2] https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.mat.ui.help%2Fgettingstarted%2Fbasictutorial.html
[3] https://help.eclipse.org/latest/index.jsp?nav=%2F51_2

[krumts]

Found a similar discussion (how to generate the eclipse help from markdown) for Egit eclipse-egit/egit#6 . Might be interesting to follow if there is some development there.

[jasonk000]

Looks good. I added a checklist to the top here.

@krumts One question; I think the migration should include adding a pointer from the old wiki to the new docs page. Thoughts? Or do you expect to drop the older wiki entirely?

[krumts]

@jasonk000 My initial thought was that we move the content from the Wiki, delete it from there, and leave there only a link to the new location. I was too slow with the changes and the Wiki is already in read-only mode - I can't modify it any longer.
I was wondering, but haven't asked the Eclipse webmasters if I could somehow temporarily get write access again or if they could drop our pages. Looking at one of the last mails about it and at the deprecation plan [1] the wiki is already being converted to static pages (may be already done), so I guess the only realistic option is to drop them.
I intend to ask, but let us move all the content first.

The plan AFAIU is that the wiki will be shut down in 2026, so that is the latest point when the outdated content would be gone.

[1] https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan