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.

[wimjongman]

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.

Thanks, I did not see it. When your committer paperwork is done you can also submit.

[wimjongman]

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

https://eclipse.org/BIRT

[wimjongman]

I filed: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/issues/892

[wimjongman]

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

All committers. Please ping us if we don't respond.

[wimjongman]

Thanks, for your analysis, Ed. It is really helpful.

I have converted this to a discussion so that from here we can create individual issues. Let's tackle this one by one.

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 have filed: https://bugs.eclipse.org/bugs/show_bug.cgi?id=577748 to close the forum. Apparently, that has not been resolved completely. I have pinged the webmasters.

[wimjongman]

Please also note that people are asking questions on that bloody StackOverflow. [1]

[1] https://stackoverflow.com/questions/tagged/birt

[wimjongman]

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 :

You will have to create these pages yourself if you think it is important. We have made it extremely easy to add and change content.

[hvbtup]

Only for committers. PRs do not work at the moment obviously - see eclipse-birt/birt-website#25

[hvbtup]

Im am watching the "birt" tag on SO and answering those questions I can answer more or less daily (https://stackoverflow.com/users/2814025/hvb).
I think that for asking and answering questions it is a well-established platform. In fact I sometimes find my own old answers when I am looking for some BIRT how-to.
I really like StackOverflow. It is kind of a Google on steroids for developers. And it is a one-stop address: I don't need to remember where to look for answers for BIRT, for Eclipse, for Oracle SQL, for Python (you name it).

[wimjongman]

Im am watching the "birt" tag on SO and answering those questions

Cheers!

[wimjongman]

This page directs the user to the forum:
https://projects.eclipse.org/projects/technology.birt/contact

I have update that page.

[wimjongman]

And if I go to this page:
https://eclipse.github.io/birt-website/docs/community

Ed, there is an "Edit this page" link in the bottom of that page. Can you try that to see if it works for non committers?

[merks]

Yes, there is.

[TheLaserNinja]

This is where the old BIRT Exchange was an incredibly helpful and powerful tool. It was a one stop shop for all things BIRT and linked to everything relevant, including blog posts, articles, our books, the Eclipse links, and any commercial contributors and implementations with BIRT (where they wanted to let us link). We had evangelists who maintained that site, answered questions on both the forums and in the Eclipse groups, and some awesome examples and plug-ins sections. Plus, with funding, we were able to do contests and such to help bring interest to the project. I'm wiling to entertain any ideas on doing something similar now. I can talk to some of the old evangelists and gauge if they'd be interested in helping out.

[wimjongman]

That would be fantastic. Preferably on our website so that it is not lost again.