search

devacfr / reflow-maven-skin

Reflow is an Apache Maven site skin built on Bootstrap. It allows various structural and stylistic customizations to create a modern-looking Maven-generated website.
http://devacfr.github.io/reflow-maven-skin/
Apache License 2.0
8 stars 3 forks source link

Documentation #100

Open almostobvious opened 7 months ago

almostobvious commented 7 months ago

Hey there. Love the work you are doing and using reflow for a while now.

My main problem is lack of reference documentation consistent with the version of reflow I am using. It's a tricky time with major changes in doxia and elsewhere but either way it's almost impossible to understand a lot of the documents that are already there and work out where to look for specific bit of information.

Take this for example: https://devacfr.github.io/reflow-maven-skin/release-notes/release-notes-2.3.html. Release notes here say the header component now supports banner and custom types. But where do I find the documentation for how to do this? Where is the header tag documentation?

Between this and maven-site-plugin schema (which BTW shows the new "site" docs not the old "project" schema which I can't find anywhere) I am spending all my time scratching my head.

So here are two suggestions

  1. Create the "Reference" page in documentation, providing a full list of reflow tags for site.xml. From there you can link to an existing page where you've documented it. It would be nice to have something like doxia site schema rendering (https://maven.apache.org/doxia/doxia-sitetools/doxia-site-model/index.html)
  2. Link to previous versions of the schema! This way one can easily find supported tags in the version they are using!

In any case, many thanks for the work and nice themes. Really appreciate it!

devacfr commented 7 months ago

Hi @almostobvious, Thank you for your feed back and this good idea. I will work on it when I have more time.

almostobvious commented 7 months ago

Hey, thanks for picking this up!

My second point perhaps wasn't clear. The suggestion is to provide access to historical reference pages (of course, up to a point). So, if I am using version X of reflow-maven-skin, I can still find the schema docs for X when the plugin moves to version Y.

There are a bunch of ways to do this - I'm sure you'se seen a few. API dev portals / swagger editors seem to do a good job of this. Publishing would go to hostname/version/uri rather than hostname/uri and UX could be as simple as having a dropdown to select doc version. Publishing also creates the "latest" link where you'd go by default.

This is a 'nice to have'. I can always look at source, but of course - looking at source across multiple artefact versions is not fun, it's time consuming and also not easily searchable.

BTW - this would be fantastic addition to standard maven artefact doc sites.