Re: [tycho-dev] VOTE: Move source & reviews to Github

[Mickael Istria <mistria@xxxxxxxxxx>]

On Mon, Mar 29, 2021 at 10:12 AM Christoph Läubrich <laeubi@xxxxxxxxxxxxxx> wrote:

The cool thing about GH-Wiki is that you can checkout it as a git-repro
and work with it "like code":
https://docs.github.com/en/github/building-a-strong-community/adding-or-editing-wiki-pages#adding-or-editing-wiki-pages-locally

Sure, but doc in the source tree also allows that very well ;)

 

anaother option would be do have simply README.MD files for example to
document a plugin and link those on the main-wiki.

There are some Maven standard ways to generate "scoped" documentation, see https://www.eclipse.org/tycho/sitedocs/ . I started moving documentation away from wiki to such doc (see https://wiki.eclipse.org/index.php?title=Tycho%2FTarget_Platform&type=revision&diff=442731&oldid=442138 ), this brings the benefit that the fine-grained doc about mojo and parameters shows as hover doc in all tools. So for fine-grained doc, I suggest we stick to Maven standard and for documentation that can be migrated to such Javadoc, do it from now on independently of GitHub as there is already a value gain, that will still be present after a migration to GitHub.

When it comes to more coarse-grained and convoluted user-stories that cannot be captured by some description in the code, we could indeed use a README.md. Maven sitedocs have capability to put arbitrary content, but this is or a README doesn't make much difference to me (and we could just link one to the other, or the other way round).

--

Mickael Istria

Eclipse IDE developer, for Red Hat Developers