mat icon indicating copy to clipboard operation
mat copied to clipboard

Published 20 hours ago • verified publisher icon eclipse-mat

Migrate MAT Content from Eclipse Wiki

Open eclipsewebmaster opened this issue 1 year ago • 8 comments

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

====

eclipsewebmaster avatar May 08 '24 21:05 eclipsewebmaster

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?

krumts avatar May 15 '24 08:05 krumts

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.

kgibm avatar May 15 '24 13:05 kgibm

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

jasonk000 avatar May 15 '24 22:05 jasonk000

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 avatar May 16 '24 07:05 krumts

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.

krumts avatar May 16 '24 09:05 krumts

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?

jasonk000 avatar Jun 13 '24 11:06 jasonk000

@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

krumts avatar Jun 13 '24 12:06 krumts

I uploaded a bunch of content in #141 and across to the wiki.

The only things I think are outstanding are:

  • Check the OQL docs are needed or not, I did not (yet) look at this.

  • Remove and clear out the old wiki pages to avoid any confusion

jasonk000 avatar Aug 31 '25 02:08 jasonk000