Documentation -divided the README file into parts #109

bartoszbicz96 · 2020-10-22T12:30:02Z

Created new files of documentation added to new folder documentation.
Modified README file.

lmarniazman

Thanks for the PR! A few comments regarding the split of this readme into seperate files.

After these are resolved, the next step would be to include these new asciidocs in the wiki. For that, we need "Home.asciidoc", "_Sidebar.asciidoc" and "_Footer.md".

There isn't really any content yet for "Home" except for this one sentence that is written in the readme under "sonar-devon4j-plugin". You can simply paste this sentence in there as a placeholder. If you want you can further this description already, otherwise we can still extend it later.
The footer can simply be copied from the documentation folder of other devonfw repos
The sidebar contains all links to the docs you just created. See the sidebar files of other repos for reference.
One more comment to the Wiki: There already is some content there written by @hohwille. I would propose to put the setup guide into its own file (guide-setup.asciidoc for example) and discard the other two pages, as they are basically empty.

After the wiki is complete, we need to think about which parts of our documentation should be added to the devonfw guide and create a master document which contains those chapters.
First focus on making the Wiki work and we will then proceed onto this master doc.

lmarniazman · 2020-10-22T12:47:10Z

documentation/3rd Party Rules.adoc

@@ -0,0 +1,12 @@
+=== 3rd Party Rules


Could you rename the .adoc files like they are in the devon4j documentation?

E.g. this file could be called "rules-thirdparty.adoc", the file for architecture rules could be called "rules-architecture.adoc", etc.

Rename "devonfw Java Quality Profile.adoc" to "qualityprofile.adoc"

"Installation.adoc" and "Configuration.adoc" can be refactored to lower-case

lmarniazman · 2020-10-22T12:53:30Z

README.adoc

@@ -6,132 +6,3 @@ image:https://travis-ci.com/devonfw/sonar-devon4j-plugin.svg?branch=master["Buil

 Plugin for https://sonarqube.org[SonarQube] to validate https://github.com/devonfw/devon4j/blob/develop/documentation/coding-conventions.asciidoc#packages[devon4j architecture].

-== Motivation


The newly created .adoc files should be referenced with a link in the readme. See readme of devon4j

lmarniazman · 2020-10-22T13:16:48Z

documentation/Architecture Rules.adoc

+== Architecture Rules
+
+The following image illustrates the devonfw architecture rules. The arrows show the allowed dependencies in green, discouraged dependencies in orange and forbidden dependencies in red.
+image:DevonArchitectureRules.png["Devon Architecture Rules",link=DevonArchitectureRules.png]


Careful with pictures, you should relocate them into the documentation folder so they can be found from the asciidoc. I would recommend creating a seperate folder for images inside the documentation folder. The value of 'link' would then be "images/[name_of_picture].png"

…es folder

lmarniazman

The documents for installation and configuration should be renamed to lowercase, and there are two other small comments in the readme, but looking great otherwise!

I was also thinking if we should maybe change the levels of the rule chapters. The way it is right now, "Architecture Rules" is on level 2 and all the rule implementations are on level 3. Of course all our rules are checking for architecture, but IMO only the chapters "Component", "Layer" & "Scope" should be subchapters of "Architecture Rules". All the other level 3 chapters aren't really related to these dependency issues that are shown in the "DevonArchitectureRules.png".

My suggestion would be to have all rule chapters on level 2 except for component, scope, and layer rules. Maybe even rename the chapter "Architecture Rules" to "Architectural Dependency Rules" or "Dependency Rules"? WDYT @hohwille ..?

lmarniazman · 2020-10-23T12:38:18Z

README.adoc

+* link:documentation/motivation.adoc[Motivation]
+* link:documentation/installation.adoc[Installation]
+* link:documentation/configuration.adoc[Configuration]
+* link:documentation/motivation.adoc[Motivation]


Motivation is referenced twice here

lmarniazman · 2020-10-23T12:43:43Z

README.adoc

+* link:documentation/motivation.adoc[Motivation]
+* link:documentation/qualityprofile.adoc[devonfw Java Quality Profile]
+
+=== Rules


I would keep the order of the rules the same way as they are in the current readme. The first three chapters are fine, but the fourth should be "Scope", then "Package", "3rd Party", etc.

lmarniazman · 2020-10-23T13:09:07Z

Also there seems to be some merge conflict here, could you resolve this @bartoszbicz96 ?

lmarniazman

Just a few comments regarding the levels of our chapters, but otherwise it's really starting to come together, thanks!

lmarniazman · 2020-10-27T12:35:42Z

README.adoc


-== Installation
+* link:documentation/rules-architecture.adoc[Architecture Rules]


The level for this bullet is fine, but I would indent the next three bullet points one further using ** instead of *. So that the chapters "Layer", "Component" & "Scope" are subchapters of "Architectural Dependency Rules".

lmarniazman · 2020-10-27T12:39:39Z

README.adoc


-This `sonar-devon4j-plugin` provides a plugin extending https://sonarqube.org[SonarQube] with the ability to validate your Java code according to the devon4j architecture.
+== Architectural Dependency Rules


All our rules are "Architecture Rules", so I would put this as a header here. Then the first bullet point under this header could be "Architectural Dependency Rules" with its three subchapters "Layer", "Component" & "Scope".

So basically: Put "Architecture Rules" here, and put "Architectural Dependency Rules" as the first bullet point with a link to the document. Also don't forget to rename the document and its title, so that everything is consistent.

lmarniazman · 2020-10-27T12:41:52Z

README.adoc

-If you have https://sonarqube.org[SonarQube] installed, you only need to go to its marketplace and install the latest version of this `sonar-devon4j-plugin`.
-Further you need to import the devonfw quality profiles (or activate all the rules of this plugin in your quality profile).
-For further details read the https://github.com/devonfw/sonar-devon4j-plugin/wiki/guide-sonar-qube-setup[SonarQube setup guide].
+== Implementation Rules


I don't think we need to put these under a seperate header, as they are also in some way architectural rules. Just put the next four bullets as level one bullet points under the header "Architecture Rules".

lmarniazman · 2020-10-27T12:43:18Z

documentation/Configuration.adoc

@@ -0,0 +1,18 @@
+== Configuration


Could you rename this file and "Installation.adoc" to lowercase?

i think i made it... anyway i will try to fix it

lmarniazman · 2020-10-29T18:58:35Z

documentation/rules-component.adoc

@@ -0,0 +1,14 @@
+=== Layer Rules


This doc should contain the component rules

lmarniazman · 2020-10-29T19:00:35Z

documentation/rules-namingconvention.adoc

@@ -0,0 +1,13 @@
+=== Naming Convention Rules


All headers for rule documents should be on level two, so starting with "==", except for component, layer and scope rules, to be consistent with the changes from your last commits.

IMHO we should follow the general best-practices from devonfw:
Simply start any AsciiDoc file on Level1.
When including the documents in the main AsciiDoc-file for the PDF set [leveloffset=«number»] to increase the level so that the result fits to our needs.

lmarniazman

Looks great now! I will approve this and then we can continue with the integration of this new documentation into the devonfw documentation pipeline in a seperate PR.

hohwille · 2020-11-05T09:19:03Z

@bartoszbicz96 thanks for this PR.
However, was there any dicussion or rationale in advance to do this?
Many github projects want to show the main aspects and features at a glance in the REAME as this is the first thing people find on github.
Was it too overwhealming?
Should we should ask the community wheter it is better to have it all in one place or split it up into tiny little bits?

Further we should also consider document generation for this repo like we have for all other projects.
Therefore we need to consider include vs. link, etc..

lmarniazman · 2020-11-05T11:57:05Z

@hohwille
The goal here was to have the documentation of this repo included in the devonfw guide. I thought splitting the different chapters of our readme into seperate files would make things easier for us with the document generation, as it is that way in other repositories too.
Maybe we could have the first few chapters (Motivation, Installation, Configuration, devonfw Java Quality Profile) displayed normally in the readme, and reference the documents for the different rule types with a link?

hohwille · 2020-11-05T15:05:49Z

Thanks for the explanation. I got the rationale now and indeed we agreed in devonfw to put all documentation into a documentation folder and follow common practices.
As always we observe things in devonfw to grow over time. Therefore we should also consider that it is time to say that we not only have "just a README" here but some real documentation that will get more complex over time. In that case we should follow how it is done in other repos like devon4j or ide where we generate a PDF documentation as part of the build process and also deploy this documentation alongside with every release:

We need to restructure a little and introduce a parent pom with pom packaging
this one should include the current plugin and the documentation as modules
the documentation then also becomes a pom.xml that derives from docgen.
as a result we then get the documentation alongside as e.g. here: https://repo1.maven.org/maven2/com/devonfw/tools/ide/devonfw-ide-doc/2020.08.002/devonfw-ide-doc-2020.08.002.pdf

Would it be possible to update this PR accordingly?

lmarniazman · 2020-11-05T15:14:06Z

Perfect, thanks for the pointers. Sure, I will connect with Bartosz and we will get on the tasks.

So just to clarify: Is the readme fine as it is in this PR?

hohwille

Thanks for taking this further. However, this still can not work. Have you tried to build it and check if the PDF gets generated and installed into maven repo? IMHO this can not work anymore after removing the docgen parent.

hohwille · 2020-11-12T08:14:01Z

documentation/pom.xml


+    <groupId>com.devonfw.tools.sonar-devon4j-plugin</groupId>
+    <artifactId>devonfw-docgen-pdff</artifactId>


Looks like a typo and this does make sense to me. Why dont we still inherit this from devonfw-docgen-pdf?

hohwille

I think it is OK to change the README to link to the actual contents in the documentation folder.
Further, the README is "just" the starting point for documentation when people directly go to this repo on github.
For the PDF we would need an additional file that uses include tags rather than links.
I have the following observations and suggestions for improvement:

IMHO splitting all the subsections of the rules into individual asciidoc file is too fine grained.
In the most extreme case users have to click a link to get one sentence of information:
https://github.com/devonfw/sonar-devon4j-plugin/blob/cd966e96ee18f815669611c73d81d38149561071/documentation/rules-package.adoc
I would instead keep these rules stuff all in one asciidoc file. The other splitting in configuration, installation, etc. makes perfectly sense to me.
After the restructuring the image is not displayed anymore:
https://github.com/devonfw/sonar-devon4j-plugin/blob/cd966e96ee18f815669611c73d81d38149561071/documentation/rules-architecturaldependency.adoc
IMHO this happened because the newline was removed before the image tag. It is important to fix this. Esp. for the PDF the image should be embeded rather than an external link.
As already agreed we should add the PDF generation so it gets deployed alongside with every release.

hohwille

IMHO now ready to be merged. Thanks to all who contributed. 👍

broke the README file into parts

97b7e79

lmarniazman suggested changes Oct 22, 2020

View reviewed changes

bartoszbicz96 added 3 commits October 23, 2020 13:48

changed convention of file names, added links in README, created imag…

edf15e7

…es folder

deleted png

343a489

changed names of 2 files, and missed character in a file README

bdb12b4

lmarniazman suggested changes Oct 23, 2020

View reviewed changes

changed level of rule chapters, order change

292ef8d

bartoszbicz96 requested a review from lmarniazman October 27, 2020 11:16

lmarniazman suggested changes Oct 27, 2020

View reviewed changes

bartoszbicz96 added 2 commits October 29, 2020 09:26

Readme subchapters modification, rename of architecture rules file

8e14966

modified architectural dependency rules file

810c4db

bartoszbicz96 force-pushed the documentation_for_sonar-devon4j-plugin branch from 895988a to 810c4db Compare October 29, 2020 11:57

bartoszbicz96 requested a review from lmarniazman October 29, 2020 17:28

lmarniazman suggested changes Oct 29, 2020

View reviewed changes

bartoszbicz96 force-pushed the documentation_for_sonar-devon4j-plugin branch 3 times, most recently from 26ff0a1 to 810c4db Compare November 2, 2020 11:30

edited levels of chapters

06eb86d

bartoszbicz96 force-pushed the documentation_for_sonar-devon4j-plugin branch from 941d3b6 to 06eb86d Compare November 2, 2020 11:54

Merge branch 'master' into documentation_for_sonar-devon4j-plugin

961109a

lmarniazman approved these changes Nov 2, 2020

View reviewed changes

bartoszbicz96 added 2 commits November 9, 2020 12:46

Added and modified pom.xml files

5c65880

modified parent tag

cd966e9

lmarniazman added this to the release:2020.12.001 milestone Nov 10, 2020

hohwille requested changes Nov 12, 2020

View reviewed changes

hohwille requested changes Nov 13, 2020

View reviewed changes

created devonfw-sonar... to create pdf documentation

67d1b3b

bartoszbicz96 requested a review from hohwille November 24, 2020 10:51

hohwille modified the milestones: release:2020.12.001, release:2020.12.002 Dec 8, 2020

hohwille modified the milestones: release:2020.12.002, release:2020.12.003 Dec 17, 2020

bartoszbicz96 and others added 9 commits December 18, 2020 09:41

Merge branch 'master' into documentation_for_sonar-devon4j-plugin

f67b809

updated docgen to 2021.04.001

fb6f86a

Update qualityprofile.adoc

6bfca8e

Update rules.asciidoc

380b286

Update configuration.adoc

4e42eb7

Update installation.adoc

e7e60d0

Update motivation.adoc

3888a54

Update pom.xml

e3718d1

Update rules.asciidoc

80b21d8

hohwille approved these changes May 10, 2021

View reviewed changes

hohwille linked an issue May 10, 2021 that may be closed by this pull request

split documentation #125

Closed

hohwille merged commit 1288df2 into devonfw:master May 10, 2021

hohwille mentioned this pull request Jun 10, 2022

Build broken #140

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation -divided the README file into parts #109

Documentation -divided the README file into parts #109

bartoszbicz96 commented Oct 22, 2020

lmarniazman left a comment

lmarniazman Oct 22, 2020

lmarniazman Oct 22, 2020

lmarniazman Oct 22, 2020

lmarniazman left a comment

lmarniazman Oct 23, 2020

lmarniazman Oct 23, 2020

lmarniazman commented Oct 23, 2020

lmarniazman left a comment

lmarniazman Oct 27, 2020

lmarniazman Oct 27, 2020

lmarniazman Oct 27, 2020

lmarniazman Oct 27, 2020

bartoszbicz96 Oct 27, 2020

lmarniazman Oct 29, 2020

lmarniazman Oct 29, 2020

hohwille May 10, 2021

lmarniazman left a comment

hohwille commented Nov 5, 2020

lmarniazman commented Nov 5, 2020

hohwille commented Nov 5, 2020

lmarniazman commented Nov 5, 2020

hohwille left a comment

hohwille Nov 12, 2020

hohwille left a comment

hohwille left a comment

		@@ -6,132 +6,3 @@ image:https://travis-ci.com/devonfw/sonar-devon4j-plugin.svg?branch=master["Buil

		Plugin for https://sonarqube.org[SonarQube] to validate https://github.com/devonfw/devon4j/blob/develop/documentation/coding-conventions.asciidoc#packages[devon4j architecture].

		== Motivation


		== Installation
		* link:documentation/rules-architecture.adoc[Architecture Rules]


		This `sonar-devon4j-plugin` provides a plugin extending https://sonarqube.org[SonarQube] with the ability to validate your Java code according to the devon4j architecture.
		== Architectural Dependency Rules


		<groupId>com.devonfw.tools.sonar-devon4j-plugin</groupId>
		<artifactId>devonfw-docgen-pdff</artifactId>

Documentation -divided the README file into parts #109

Documentation -divided the README file into parts #109

Conversation

bartoszbicz96 commented Oct 22, 2020

lmarniazman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmarniazman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmarniazman commented Oct 23, 2020

lmarniazman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmarniazman left a comment

Choose a reason for hiding this comment

hohwille commented Nov 5, 2020

lmarniazman commented Nov 5, 2020

hohwille commented Nov 5, 2020

lmarniazman commented Nov 5, 2020

hohwille left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hohwille left a comment

Choose a reason for hiding this comment

hohwille left a comment

Choose a reason for hiding this comment