What kind of documentation do you need or feels incomplete?

[laeubi]

Hello Tycho-User,

we recently get some feedback from our users that Tycho seems not well documented. Just as a recap we currently have the follwoing sources of information:

• The site-docs: https://tycho.eclipseprojects.io/doc/latest/
• The Wiki-Pages: https://github.com/eclipse-tycho/tycho/wiki (previously https://wiki.eclipse.org/Tycho/ with outdated-content and wee are currently seeking for help to migrate!)
• Some demos: https://github.com/eclipse-tycho/tycho/tree/master/demo
• There are some blog posts around:
  • http://blog.vogella.com/2019/11/25/pom-less-tycho-enhanced/
  • https://github.com/vogellacompany/tycho-example
  • https://www.vogella.com/tutorials/EclipseTycho/article.html
  • https://läubisoft.gmbh/en/articles/using-maven-artifacts-in-pde-rcp-and-tycho-builds/

As it is always hard to duess what exactly would be most helpful we like to get some feedback from our users / community how we can improve here:

• Are the resource incomplete or hard to understand?
• Are these maybe just hard to find and/or to scattered around?
• Would mabye some maven-archtypes to genearate starter projects help?
• ....

Any feedback would be appreciated, and if you even can help enahnce some of the resources that would be great as well!

[jcompagner]

the biggest problem i have current is if you search for, for example "tycho-p2-plugin"
(in bing or google)

the first hits you get is always:

https://www.eclipse.org/tycho/sitedocs/tycho-p2/tycho-p2-plugin/index.html

which are all removed..

somehow it would be nice if we have redirects there configured?

[laeubi]

@lppedd would you like to apply your suggested change to the wiki?

It seems a Wiki can now also be used like a "normal" git repository with PRs and so on so that would be interesting to try out:

https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages

if it all works out well you might want to add a section to the contributing.md for further reference?

[lppedd]

@laeubi well apparently I've just edited the Wiki without any PR 👀
I thought it would spawn one, but it just applied the changes. You might want to restrict access from the settings.

[laeubi]

Can you give a reference for the page you edited? I'll then need to ask EclipseInfra, maybe you are a committer of an Eclipse project and thus allowed to edit everywhere? till sounds a bit strange!

[lppedd]

@laeubi I have edited the main GitHub Wiki page. See revisions https://github.com/eclipse-tycho/tycho/wiki/Home/_history.

thus allowed to edit everywhere

No no, this is only related to GitHub and its settings.

[laeubi]

I have opened: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/issues/2163 even though I think it is not bad in general (faster/better adjustment) we should still check who can do this before we decide if it is good/bad :-)

[HannesWell]

Currently also the wiki of this Github repo also contains some amount of documentation.
Most of that content looks suitable to be moved to a extra section in the site-docs as well, but IIRC that was already discussed.

[laeubi]

Eclipse Infra has created the redirects for the Tycho site-docs, if it does not work it might help to clear the browser cache or try a private browser window, if you still se issues let us know!

[Bananeweizen]

Just a tiny side note: I thought the discussion about the new domain for eclipse projects was not yet settled? Therefore we may want to be careful announcing it heavily in this thread.

Regarding documentation improvements:

• we might want to link from the site-docs to the wiki also (basically just have the wiki page urls in the javadoc parts of the mojos)
• if you know which blog posts, youtube videos etc. are useful, just have them added in the readme. I totally like if open source projects link to tutorials made by users, even though those may be more inconsistent than a "centrally managed" collection of tutorials.
• I have used maven archetypes maybe two times in my entire life. A page describing the necessary steps like "copy this template first", "change id to your project id", ... feels generally more consumable to me. Typical end users probably don't create new Tycho projects every week, therefore more automation might not have that much of an effect.
• We should remove the artificial separate between core and extras that is still reflected in site-docs. E.g. make everything in the left hand side toc similar, and try to flatten the right hand side module list (not sure if that is possible).

[laeubi]

Just a tiny side note: I thought the discussion about the new domain for eclipse projects was not yet settled? Therefore we may want to be careful announcing it heavily in this thread.

This is what we got from the foundation, and what we use, I have no information that this might change or is considered temporary in any way. I just read some rumour about no longer using eclipse.org/project name anymore....

we might want to link from the site-docs to the wiki also (basically just have the wiki page urls in the javadoc parts of the mojos)

That's a good point, at least for the generic stuff. But maybe it is then better to embed the info in the sitedorc directly?

if you know which blog posts, youtube videos etc. are useful, just have them added in the readme. I totally like if open source projects link to tutorials made by users, even though those may be more inconsistent than a "centrally managed" collection of tutorials.

👍 if you have something in mind, just edit the readme right now!

I have used maven archetypes maybe two times in my entire life. A page describing the necessary steps like "copy this template first", "change id to your project id", ... feels generally more consumable to me. Typical end users probably don't create new Tycho projects every week, therefore more automation might not have that much of an effect.

I haven't used them much either, but I it seems often used in some areas like spring, maven itself and so on so I wonder if thats maybe something users of Tycho would expect as well. Also it would be possible to "ship" this with a release, so if things change over time we can adjust it directly in the repository.

We should remove the artificial separate between core and extras that is still reflected in site-docs. E.g. make everything in the left hand side toc similar, and try to flatten the right hand side module list (not sure if that is possible).

This sounds good, "extras" is really obsolete this days and I already moved some stuff from extras > "core", so I think as we are at new major release now we can even move more around.

[UdoW]

I would like to have a migration guide from Tycho 2.x to 4.x (probably a step between to 3.x is necessary) and what improvements are achieved when you do this (as a stimulus for all). The important parts should be mentioned in prose to see the difference easily. I would not recommend to give an example project only (it would help, true, but not alone).

A central page where all common (to be defined) topics are listed and all the links to the details pages would be helpful. This might be part of the Github wiki pages but should be updated for each version release.

[laeubi]

@UdoW we already have:

• https://github.com/eclipse-tycho/tycho/blob/master/RELEASE_NOTES.md#migration-guide-2x---3x
• https://github.com/eclipse-tycho/tycho/blob/master/RELEASE_NOTES.md#migration-guide-3x--4x

does this helps?

Beside that we try to migrate some important information as part of the sitedocs you can see the current work here:
https://tycho.eclipseprojects.io/doc/master/index.html

If you think anything is missing or unclear let us know or even just hit the edit button on Github to suggest a change!