Hi Zoran,
Thanks for the approval & useful feedback.
I've made the changes as discussed below and pushed them to my forked
repositories for camel & camel-website (https://github.com/klease/camel
& https://github.com/klease/camel-website/). The changes from the main
repo are also merged & pushed to my fork; not sure that was necessary or
not.
I added some more detail inline below about the changes I made.
Running "yarn preview" and viewing the generated site locally looks
good, as well as the link check.
Before creating the pull requests I have a few more questions.
1. There is no contributing.md file in the camel-website/community
content but there is both a CONTRIBUTING.md file at the root of the
camel repository as well as the file
docs/user-manual/modules/ROOT/pages/contributing.adoc. All the
contributing links in the website reference the HTML file generated from
the .adoc file. The camel/README.md file references CONTRIBUTING.md.
These files are similar but not identical and both have been modified
recently. Would it make sense to also move the contributing.md file to
the community content & reference that one from everywhere, including
the main README?
2. The camel/REAMDE.md has links to mailing-list and support pages which
are just http://camel.apache.org/support.html but end up on the
generated HTML pages in the user-manual so they'll be broken. I assume
it needs to be changed to https://camel.apache.org/community/support/?
3. When running "yarn preview" I hit the limit of unauthenticated API
requests on github to get the issues when building the release notes.
This gives errors like this "ERROR 2021/05/04 15:34:06 Failed to get
JSON resource
"https://api.github.com/repos/apache/camel-k-runtime/issues?state=closed&milestone=10":
Failed to retrieve remote file: Forbidden". Waiting a while and trying
again allows it to finish. There doesn't seem to be any way to
authenticate on the getJSON request in the Hugo template. It might be
worth mentioning it in the doc about building the website locally :)
Cheers,
Karen
On 29/04/2021 10:41, Zoran Regvart wrote:
Hi Karen,
thank you for doing the analysis and for the very thoughtful plan.
Replies are inline.
On Wed, Apr 28, 2021 at 11:56 AM Karen Lease <karenlease...@gmail.com> wrote:
[snip]
1. Compare & merge more recent changes from adoc files to md files and
remove the .adoc files.
+1, I prefer the manual to be focused on using Camel, and the
community bits outside of the manual
KL: Done, main changes were in the user-stories and team lists. I also
added the Nabble links to the mailing-list page.
2. Change links in the user manual navigation, assuming we want to
reference those pages in the user manual.
+1, I think, since we have the top menu for Community we can also
remove these from the manual. Those are in
docs/user-manual/modules/ROOT/nav.adoc of the apache/camel repository
on GitHub
KL: In the nav.adoc files, I left the links Resources & Guides/Books
and the Community links which I didn't move (Contributing, Release
guide, Chat room) as well as FAQ/How can I get help? which directly
points to the support page. I used "link:/community/xxx/" which works in
preview mode. Using a relative link like ../../comunity/xxx in the
nav.adoc files doesn't work because it's included at different levels
(user-manual & user-manual/faq.) I suppose these could be completely
removed instead, especially if we also move the "Contributing" page to
community.
3. Change the footer link to mailing-list to reference the md page
instead of the adoc page.
+1, two changes are needed, due to using Antora and Hugo to build the
website we have two sets of templates, in:
antora-ui-camel/src/partials/footer-content.hbs and
layouts/partials/footer.html of the apache/camel-website repository on
GitHub
4. Possibly add a Mailing List section to the main Community page to be
consistent with the Footer link. It is linked from the Support page already.
+1, folk often miss the mailing list I think, this would help more
folk in finding it.
KL: I added it; for now it has the same icon as the Support link
5. Check and fix embedded links to the user manual pages which would be
replaced with the pages generated from the .md files. As far as I can
tell, there aren't too many.
+1, we have a link checker in the website run with `yarn check:links`,
it'll check all site relative links, and another checker (run with
yarn check:html) forbids links to camel.apache.org that are not site
relative. I suspect there might be a fair bit of xref links to the
community from the user manual or perhaps from components or sub
projects as well. Hopefully the checks will catch them all.
What's your feedback on this plan?
Sounds like you have a very clear understanding of what we need fixed.
Please do reach out if you find any issues or need any help with this.
Thanks!
zoran
