search

eclipse-mat / mat

The Eclipse Memory Analyzer is a fast and feature-rich Java heap dump analyzer that helps you find memory leaks and reduce memory consumption.
https://eclipse.dev/mat/
Eclipse Public License 2.0
59 stars 10 forks source link

Migrate MAT Content from Eclipse Wiki #49

Open eclipsewebmaster opened 4 months ago

eclipsewebmaster commented 4 months ago

| --- | --- | | 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

====

krumts commented 3 months ago

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

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:

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

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

jasonk000 commented 2 months ago

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 commented 2 months ago

@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