Hi Zoran,
Thanks for your explanations about the editing process and the reason
for the duplicated adoc & md files.
I found that besides the user-stories files, there are a few other files
referenced in Community which are also duplicated. There are also some
slight inconsistencies in the links between the Community page linked
from top menu and the Community links in the page footers on the
generated site. I made the following table which shows the source files
and which one is used where. Hopefully the formatting will be clear in
the mail.
In the first column are the .adoc files in
camel/docs/user-manual/modules/ROOT/pages. In the second comun are the
.md files in camel-website/content in the community (comm) and docs
folders. The other columns show which file is referenced in which links.
The links in the User manual Nav menu are on the left. They are all
under the Community heading except Books & Building which are under
"Resources and Guides". The links in the "Main page" column are in
https://camel.apache.org/ in the section "Apache & Opensource".
It appears that the 2 md files in camel-website/content/docs are not
currently referenced in the generated site.
FILES | REFERENCES
-----------------------------------------------------------------------------------------------------------
user-manual .adoc | camel-website .md | User manual Nav | Top
menu/Community | Footer/Community | Main page
-----------------------------------------------------------------------------------------------------------
contributing | | adoc |
adoc | adoc | adoc
release-guide | | adoc |
- | - | -
mailing-lists | comm/mailing-list | adoc |
- | adoc | md
support | comm/support | adoc |
md | md | -
team | comm/team.md | adoc |
md | md | -
user-stories | comm/user-stores | adoc |
md | md | -
- | comm/articles | - |
md | md | -
books | comm/books | adoc |
md | md | -
- | comm/sources | - |
- | - | md
- | comm/camel-extra | - |
- | - | -
building | docs/building | adoc |
- | - | -
- | docs/sources | - |
- | - | -
Definitely it would be preferable to have only one copy of
mailing-lists, support, team, user-stories & books files. So if we
followed your idea and kept the .md files for those, then we would need to:
1. Compare & merge more recent changes from adoc files to md files and
remove the .adoc files.
2. Change links in the user manual navigation, assuming we want to
reference those pages in the user manual.
3. Change the footer link to mailing-list to reference the md page
instead of the adoc page.
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.
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.
What's your feedback on this plan?
Karen
On 27/04/2021 10:10, Zoran Regvart wrote:
Hi Karen,
thanks for taking interest in our project and especially around the
documentation! Some answers inline.
On Mon, Apr 26, 2021 at 10:54 PM Karen Lease <karenlease...@gmail.com> wrote:
Thanks for the reply.
In fact, when I click the "Edit this page" link, it takes me to the git
repository page with this message:
"You need to fork this repository to propose changes.
Sorry, you’re not able to edit this repository directly—you need to fork
it and propose your changes from there instead."
I am connected with my github account but apparently that's not sufficient.
Yes, this is the process, on GitHub contributions by way of pull
requests can be done only from forks. Though clicking on "Fork this
repository" should set everything up for you and you should be able to
do edits from there and propose changes via pull requests. The preview
is done only for the changes made to the apache/camel-website
repository, for changes to other repositories (like apache/camel) we
don't have the preview. After merging the changes, if there are no
issues found by checks the website is updated in the next 20-30min.
Since the actual website matches the adoc file, I assume the md file in
camel-website is obsolete. There are some other files which have both
.adoc & .md files. Would it make sense to delete the .md files from the
camel-website if those are obsolete?
We started with content from the previous system (Confluence Wiki),
and in the process of conversion sometimes we duplicated the effort
and ended up with copies. The website gathers content from multiple
repositories (and branches) and formats (asciidoc and markdown). We
never took the time to implement a documentation strategy, as to where
what kind of content is placed. For me it would make more sense to
have the user stories outside of the user manual, that is in the
markdown file. That ends up being published here:
https://camel.apache.org/community/user-stories/
And that's the version we link from the community page
(https://camel.apache.org/community/).
If that makes sense to folk, it seems that we need to refresh that
markdown file with the changes that went into the asciidoc file in the
user manual and consider removing that copy.
zoran
