Contents removed, links borken, documentation messed up

[hohwille]

We spend a lot of work in the documentation of OASP4J.
There were clickable SVG images of the architecture linked from the architecture documentation (https://github.com/oasp/oasp4j/wiki/architecture).
Also we had a folder for every official release that was pulled out so far. This folder contained the documentation, release-notes and the entire maven-site for the release. This was very helpful to get infos about a particular release. E.g. projects using a specific version could still find the PDF and JavaDocs for exactly the version of OASP4J they started with and are currently using.

All this content has been removed from the OASP website. Links from the documentation going there are now broken and messed up. I got several requests from users that were looking for this material and could not find it anymore.

The previous content can be found here:
https://github.com/oasp/oasp.github.io/tree/014f841ece53f52fb4165abf4782b983efbe6bd5/oasp4j

I am happy that people want to innovate and improve but in this case QA entirely failed. Even though the issue is already known, nothing happens.

[hohwille]

Should be fixed now. Still waiting for gh-pages to be synced before closing...
https://oasp.github.io/oasp4j/images/T-Architecture.svg
https://oasp.github.io/oasp4j/oasp4j_roadmap.html
https://oasp.github.io/oasp4j-ide/presentations/overview/oasp4j-ide.html
https://oasp.github.io/terms-of-use.html

[hohwille]

I am totally fine with doing a restructuring and tidy up. Also we can consider moving extensive release content with maven site to an external server without git version control. The git history is not really cool here and even the reverting of folder deletion and renaming caused many megabytes of overhead. Git is a great tool but in such cases it is even worse than SVN (git can not track folders, etc.).
However, when we are going for all this tidy up lets first come up with a plan, discuss and agree on that end then get into action.

[sjimenez77]

There already were some discussions regarding the new website.

The website is the compiled built of the angular application in the repository https://github.com/oasp/oasp-new-website. Some time ago we encouraged to use the resource files in the assets folder (markdown, PDFs, etc.), as it was a requirement, in order to update the current information, summarize it and make it more usable.

For example, the OASP4JS content had been already updated to the current one, because the previous contents are deprecated. In the same way, the content of the OASP4J section should be updated using the markdown files.

Another goal was to make possible to update the information easily by any collaborator, using markdown files that will be rendered as HTML in the pages. Also, we are working to have a pipeline to automate this build and deployment process.

Anyway, the old website is under the old-website branch https://github.com/oasp/oasp.github.io/tree/old-website

[hohwille]

@sjimenez77 thanks for your hints. To explain my concerns and actions:

• I pointed out that the refactoring of the site caused many links and bookmarks to break entirely. People were actively complaining and hence some action was required.
• No action to fix the problems had happened for 3 weeks. Links were still broken.
• Therefore I wanted to help out and restore content under the old location and make the links work again.
• Please note that there are also external sites linking to OASP4J content where we can not easily update links because we do not have control over the content.

However, this topic seems to be doomed entirely.

• Something odd seems to be broken in the git history of oasp.github.io.
• Now the content is there in the git repo on master, but it does not arrive on the site.
• I just reverted deletions via regular git commands. I was not aware nor intended to cause issues with the git history. IMHO this is a bug in git itself.
• However, in the end it seems that I finally have made it even worse. I am very sorry for that but I only wanted to help making all these broken links work again.

How to proceed now?

• Should we call github support on this?
• Should we archive the site (rename repo), and create a fresh repo with the intended content only?
• Any other ideas?

[hohwille]

Another goal was to make possible to update the information easily by any collaborator, using markdown files that will be rendered as HTML in the pages.

We should also discuss on that. We decided to go for AsciiDoc what is way superior than Markdown. In order to avoid mixture and brain-dead when switching between those two formats (e.g. markdown link syntax is really odd) I proposed to use AsciiDoc consistently throughout OASP and Devon and ban Markdown usage in an architects meeting. As this was accepted I changed *.md files to *.adoc on OASP ~ a year ago. See e.g. oasp/oasp4j@5aaa0e3
See also:
https://github.com/oasp/oasp-docgen/wiki#guidelines

[sjimenez77]

The use of Markdown instead of AsciiDoc is due to the Angular component that renders HTML using the md files as input. For the moment there is no Angular component to render AsciiDoc.

The current links of the new website are not broken and they have been checked several times. If we need to update in the new website info I suggest to request the updates here as issues. It is important to point out that we will have a pipeline to automate the build and deployment of any change in the next days.

The issue with the old links happens when those links match the name of a repository inside OASP. So, if you have a link with oasp.github.io/oasp4j it will go to the oasp4j repository and not to the URL. For that reason, the links in the new website are under oasp4-j or oasp4-js to not match other repositories.

[hohwille]

For the moment there is no Angular component to render AsciiDoc.

Totally fine. Stay with markdown for the site then.