Improve the documentation for where to ask questions

[merks]

It's not easy to find out where to ask questions. When a user asks a question like this:

https://www.eclipse.org/forums/index.php/mv/msg/1110081/1850012/#msg_1850012

I ask myself, where does BIRT direct the user to ask questions?

This page directs the user to the forum:

https://projects.eclipse.org/projects/technology.birt/contact

And it's good that if one finds the BIRT forum:

http://www.eclipse.org/forums/eclipse.birt

It announces that the following is a redirect:

https://github.com/eclipse/birt/discussions

But going to this site:

https://www.eclipse.org/BIRT/

I'm redirected to this site, which is really pretty, well done!

https://eclipse.github.io/birt-website/

And if I go to this page:

https://eclipse.github.io/birt-website/docs/community

It doesn't tell me about using this page for questions:

https://github.com/eclipse/birt/discussions

And the issues link on the community page links to the following page, which is a 404:

https://github.com/eclipse/issues

It should link to this:

https://github.com/eclipse/birt/issues

So it's really quite difficult to find out where to ask question or how to report issues.

The website looks so nice and better links for issue reporting and question asking would be a nice improvement.

[hvbtup]

I created a PR for the wrong issues link on the new website a few weeks ago (eclipse-birt/birt-website#25) but this wasn't merge yet.

And the fact that the uppercase link /BIRT/ does not work on eclipse.org is a pity. Can this be changed?

Apart from these details, your question is one of those that I ask myself.

It seems that hardly anyone watches the new website for PRs.
But at the same time, it seems very important to change this to make the new website "alive".

For example, when I could not sleep last night, I thought about creating some example reports explaining single features or special topics. Originally I played with the idea of writing a new book about BIRT (since e.g. "BIRT - A Field Guide" is no longer available, and in BIRT teaching sessions, the learners often ask for a printed tutorial in German). But the rate between effort and potential commercial success seems to speak against the book idea.

So I think about where should I place example reports, short tutorials for advanced topics etc?
I could do this in the hvbtup/birt wiki but OTOH I want to reserve that to merely explain the differences to eclipse/birt.

The natural place for tutorials and examples would be a wiki on the new website.
But as long as reasonable PRs take weeks to be applied, this will prevent people from developing the wiki, and the wiki cannot really be called a wiki.

So: Who is responsible for merging PRs on the website?

I think it is very important to further improve the online documentation and (as a side effect) demonstrate that the project is alive. An improved documentation can also reduce the number of beginner questions significantly, I hope.

One thing that is lacking is a feature list, a description of what BIRT can do and what BIRT cannot do. For layout, there should be a table like this for the most important emitters (I :

Feature	PDF	HTML	DOCX	XLSX	See note
Drop: Detail:	YES	?	NO	NO	1
Barcodes	Yes*	Yes*	Yes*	Yes*	2
2D-Codes (QR, DataMatrix etc)	Yes*	Yes*	Yes*	Yes*	2

Yes* means: Not natively supported, but reasonable workaround are available.

1. Drop Detail can be specified for cells in table group header rows. It means that the cell should "drop" down into the first detail row. Normally this only make senses when specified for all non-empty cells of the row. For perfect alignment, carefully adjust border and padding properties of the header cell and the detail cell (more explanation necessary).
   and footnotes where necessary. AFAIK does not work with Word or Excel export. Also note that Word doesn't have a concept for table group header rows at all. See [drop_detail] for more details.

2. BIRT <= 4.9 does not support Barcodes or 2D-Codes like QR-Codes or DataMatrix-Codes.
   However, it relatively easy to work around this limitation. The idea is to use any Java (or possible old-style JS) library that can generate a barcode or 2D-code for a given text as an image file. For example, zxing can be used. The necessary JAR files have to be in the class path (for the designer, see Preferences / Report Design / Class Path, for POJO runtime or OSGI runtime in the class path, eg. inside ReportEngine/lib). Use a dynamic image item in the layout. Use Javascript to call the Java library and create a byte array. Use this as the source for the image data (example needed). If the image MIME type is set correctly, this even works for generating SVG images. For some 1D codes (like Code-39 oder Code-128), an easier alternative can be to use a special TrueType font.

We are still a small team.

I think it is necessary to clearly divide questions about how to use BIRT from enhancement proposals and bug reports.
Otherwise we will drown in a flood of new issues.
The first address for questions should be to look at the wiki and (my personal opinion: ) stackoverflow.com.
If a question comes up frequently, the topic should be added to the wiki.

Pure usage questions should go into birt/discussions, not into birt/issues. The categories that we have in discussions are sufficient, I think.
Is is possible to create kind of a "header" for issues and for discussions or top "pin" entries?
It would be nice if basic instructions (about where to post, usage of tags, and that noone can demand help, but everone is invited to help) would be visible at first glance.