Hello

Proxy config in eclipse/maven is an advanced topic and should be moved at the end of the guide.

Currently the reader has 5 pages on how to configure a proxy, before even using devon. These page are described as "Manual configuration" so we can expect to configure several options. But this is only for proxy, for specific configurations.

If we want to keep it in the first chapter, just mention/link to the right chapter.

Nicolas

We have established a clear naming convention for our repositories. Therefore several repos have been renamed:

• devon-ide renamed to ide (see devonfw/ide#142)
• tools-cobigen renamed to cobigen (cannot find issue)
• sonar-devonfw-plugin renamed to sonar-devon4j-plugin (devonfw/sonar-devon4j-plugin#26)

Our convention says that we follow DRY (Do not repeat yourself) and omit any devon[fw]- prefix in repository names. Further products and stacks should just carry their product name (hence just cobigen without artificial tools-) prefix.
Therefore this repo should be named just guide (or documentation if preferred, but IMHO guide is already established and fine).

Currently we have old and way too much devonfw_guide.pdf files in the history.

• Please cleanup the history and remove the pdf file from history entirely. The repository is much too big already slowing down all our github action builds.
• The hint in the readme needs to be deleted as well. The repository already reached 2GB of space just on the main branch which slows down so many clones and github actions like the website without any necessity.

Instead I would suggest the following:

• whenever there is a git tag created and successfully built on one of the assets integrated as submodule in this repository, the devonfw-guide pdf should deployed as a GitHub release with the following tag and release name: $TAG_YEAR.$TAG_MONTH.$GITHUB_RUN_NUMBER whereas TAG_YEAR and TAG_MONTH has to be derived from the new tag of the submodule triggering the build (possibly passed as a parameter or discovered from the history). Be aware that currently we have different tag schemes like 2021.04.001 or v2021.04.001 or even release/2021.04.001 all should be valid, and you should identify the sequence 2021.04 automatically in all cases and append .$GTHUB_RUN_NUMBER to it.
• Please attach / upload the devonfw_guide_$TAG_YEAR.$TAG_MONTH.$GITHUB_RUN_NUMBER.pdf to the github release.

I would like to check every statement that we do in the database section in our guide. We say about some databases that we do not support them and it is not true at all.

We need to focus not only in devon4j, but also devon4net and devon4node. For example, the default ORM for devon4node that is TypeORM fully supports MongoDB as you can read here https://devonfw.com/website/pages/docs/master-devon4node.asciidoc_layers.html but we said that we do not support it properly here https://devonfw.com/website/pages/docs/guide-mongodb.asciidoc.html.

Expected behavior

As a reader od the devonfw guide, I want to read about the defonfw-ide, so that I can understand what it is

Actual behavior

As can be seen on https://devonfw.com/website/pages/docs/master-ide.asciidoc_integrated-development-environment.html#eclipse-plugins.asciidoc , the section on eclipse plugins still refers to OASP: "5.15. OASP4J IDE Plugins:

Since an application’s code can greatly vary, and every program can be written in lots of ways without being semantically different, OASP4J IDE comes with pre-installed and pre-configured plugins that use some kind of a probabilistic approach, [...]"

This is totally confusing for everyone who does not know the history of the devonfw-ide.

Steps to reproduce (bug) / Use Case of feature request (enhancement)

1. go to https://devonfw.com/website/pages/docs/master-ide.asciidoc_integrated-development-environment.html#eclipse-plugins.asciidoc

OR

take a look at eclipse-plugins.asciidoc

Related/Dependent Issues

Comments/Hints:

Affected version: 2019-12-20 / No Version on devonfw-guide available (???)

• OS: Windows/Linux/Mac? all
• Browser: Chrome/Firefox/Safari? all

Hello,

Exemples use svn on retired Capgemini svn server.
Nowadays, everyone use git, we should switch to up-to-date examples.

Nicolas

Replace devon4ng and devon4node docs with devon4ts

Asciidoctor diagram supports different inline diagramm types which are very useful for our guide. For some types additonal setup for the generation process is required.
Supporting plantuml for creating UML diagrams directly in the devonfw docs would be very useful. For example we use plantuml in the Kafka module. Currently it required manual steps do generate the SVGs and PNGs to include them.

We should also explore alternatives like https://www.diagrams.net/

Hello,

The devon guide explains how to customize Devcon and create new modules before the reader has an opportunity to use Devcon to simply create a new project.

Advanced features & customization should only presented after the reader has created a working, new devon application by following the first chapters of the guide.

Furthermore, the Devon module examples are pushing the reader to use Devon -g to create a new project. But we will ask again to create the project , this time from the command line, in the next sections.

Nicolas

Hello,

The current introduction (chapter 1.) doesn't reflect the fully open source nature of Devon.
Text and schema are full of Capgemini-specific content : mentioning IP, Capgemini Organization, ...

In my opinion, we could mention Capgemini details in an 'history' introduction to show the evolution of devon.

But as soon as me enter Devon description, everything must be free of Capgemini details / mention.

Schemas should reflect the open source nature of the whole devon.

Nicolas

Hello

Download points to an internal server.
=> Should point to the public location.

Nicolas

Expected behavior

As a reader of the devonfw-guide, I want read up-to-date information on devonfw and devonfw-ide so that I can use it properly

Actual behavior

Section 4.3.2 of the devonfw-guide (which is ide.wiki / eclipse-plugins.asciidoc) describes FindBugs, not SpotBugs, the actually installed plugin

Steps to reproduce (bug) / Use Case of feature request (enhancement)

1. read section 4.3.2 of the devonfw-guide

Related/Dependent Issues

Comments/Hints:

https://marketplace.eclipse.org/content/findbugs-eclipse-plugin
https://marketplace.eclipse.org/content/spotbugs-eclipse-plugin

Affected version: Updated at 2020-01-10 17:48:03 UTC

As discussed in MS teams, I would like to discuss the following ideas for improvement:

• Consider omitting AsciiDoc extension in the generated HTML filenames of the https://devonfw.com website. Currently we have file extensions .asciidoc.html. Instead it would be better to have just .html if easily possible.
• Consider renaming all submodule-folders to just the stack/product name omitting the obsolete .wiki suffix
• Consider using a namespace for each stack/product in the URL of the website/pages to avoid name clashing. Currently two stacks/products could overwrite their content when they use an include with the same filename. See https://devonfw.com/website/pages/docs/master-doc.asciidoc_layers.html
• Consider shortening the filenames of the stack/product documentations. E.g. omitt master- prefix. If namespace above can be done, even use index.html/index.asciidoc as entry point for every stack/product.

ATTENTION: We only want to address quickwins. I can also assist to some degree. However, if we would make things overcomplicated and would have to add an HTML post-processing or so we can drop any of the above ideas.

Common structure for master files:

• master.asciidoc:
  All includes must be at level 0 and no titles (=, ==, ===, ...), for example:

include::general/master-general-start[leveloffset=0]
include::devon4j.wiki/master-devon4j[leveloffset=0]
include::devon4ng.wiki/master-devon4ng[leveloffset=0]

• master-*.asciidoc (devon4ng, devon4j, cicdgen, ...):
  • Must have ONLY ONE level 0 title, and it must be the first title (=).
  • No includes at level 0
  • Each include must be under one title X, and its level offset must be X+1:
    = is level 0 --> No includes at level 0.
    == is level 1 --> leveloffset=2 (because 1+1 = 2)
    === is level 2 --> leveloffset=3 (because 2 + 1 = 3)

Bad:

 = devon4ng

include::architecture[leveloffset=1]
include::meta-architecture[leveloffset=1]

== Layers

include::components-layer[leveloffset=2]
include::services-layer[leveloffset=2]

Good:

= devon4ng
    
// NO includes here  
   
== Architecture

include::architecture[leveloffset=2]
include::meta-architecture[leveloffset=2]

== Layers

include::components-layer[leveloffset=2]
include::services-layer[leveloffset=2]

• as a default rule, all the .asciidoc files should:
  • Must have ONLY ONE level 0 title, and it must be the first title (=).
  • The rest of the content must be in their own levels starting with level 1 (==)
  • Must not jump levels (writing something at level 4 without specifying level 3, 2, 1 and 0)

Bad:

// inside architecture.asciidoc file
== Some section 1
I'm under nothing, there is not level 0 and I'm level 1

==== 
My parent should be something at level 2, but I'm under level 1. My level is 3.

Good:

// inside architecture.asciidoc file

= Archtiecture

== Some section 1
I'm under architecture level 0 title. I'm level 1.

=== Other section
Im under some section 1. I'm level 2 and my parent is level 1

== Some section 2
Im under architecture level 0 title. I'm level 1

[Note: see also https://github.com/devonfw/ide/issues/330#issue-544502711 for an in-depth description of all the problems with Installation of CobiGen Eclipse Integration.]

As a non-Capgemini user, I want to install CobiGen Eclipse Integration so that I can use it.

When I follow the steps described in Section 54 Eclipse Integration (see https://github.com/devonfw/devonfw-guide/raw/master/devonfw_guide.pdf ), I am stuck with...

Open CobiGen’s update site
Insert the update site of your interest into the filed Work with and press Add …
◦ Stable releases: http://de-mucevolve02/files/cobigen/updatesite/stable/
◦ Beta/RC releases: http://de-mucevolve02/files/cobigen/updatesite/experimental/

These URLs are not accessible from outside the Capgemini organization.

Is this intended (e.g. for reasons of intellectual property)? Then, please explicitly express this restriction. If not, please provide download-locations available from outside.

I know that the pre-configures ide will include the CobiGen integration (as soon as it is available). But also non-Capgemini users may want to install the CobiGen integration by themselves.

The "Covenant Code of Conduct" from the .github repo's CODE_OF_CONDUCT.asciidoc should appear in the PDF (since it's included in the master.asciidoc file) but is missing for some reason.
When generating the guide locally using mvn clean package -Doutput.format=pdf the CoC is included in the resulting PDF.

Hello,

Current interface of Devcon has more field (database) than the screenshots of the devon guide.
=> Text is missing too for these new fields.

Nicolas

As a reader of the devonfw guide, I want to understand what devonfw is and what parts it consists of so that I do not get confused.

Thoughout the devonfw guide several terms (i.e. words) are used to refer to devonfw and its constituents. It appears to me that amoung these terms there is a (somtimes confusing) multitude of synonyms (i.e. different terms for the same concept). Other terms appear to be used not consistently (one term used for more than one concept although there are other terms available to distinguish these concepts).

I found the following terms in the devonfw guide as of December 2019 (grouped into groups of synonyms):

- devonfw (many occurrences)
- devonfw platform  (ca. 6 occurrences)

- devonfw ide (ca. 5 occurrences)
- devonfw-ide (ca. 80 occurrences)
- devon ide (ca. 4 occurrences)
- devon-ide (ca. 4 occurrences [code not counting])

- devonfw ide package (1 occurrence) [the ide package is presumably something else than the ide ==> not a synonym, right?]

- devon CLI (2 occurrences) 
- devonfw IDE CLI (1 occurrence)
- devonfw-ide CLI (1 occurrence)

- devon-dist (2 occurrences)
- devonfw distribution (ca. 28 occurrences) 
- devon distribution (ca. 7 occurrences)
- "Devon Dist" (1 occurrence) 

- devonfw package (1 occurrence) [this may or may not (???) be a synonym to devonfw distribution]

- devonfw Platform Extension Pack (4 occurrences)

- devonfw environment (3 occurrences)

[all counts include only those occurrences where there could be a synonym, e.g. code samples, URIs, ... are not counted]

==> please verify that each group is indeed a group of synonyms where all terms within a group mean the same thing under all conditions (and if my grouping was wrong, please correct by splitting the group)
==> please join synonym groups where necessary (perhaps "devonfw ide" == "devonfw environment" ???)
==> please create a glossary where for each remaining synonym group, one term is defined (explained) what it is and the synonyms are mentioned.
==> it would be great if the guide could be simplified by eliminating unnecessary (and confusing) synonyms, especially the devonfw vs. devon writing and the package vs distribution naming.

We should update to the new docgen (5.0.0+).

As a user, I want to have links in documentation files referencing themselves (its github url) so that when I see these file in the website I can click its link, go to github and modify the file.

Nowadays when you find an error through the website, you don't know which file to modify so it is difficult to contribute.

devonfw/devonfw.github.io#77