(httpd-site) branch main updated: docs-project: Deduplicate, fill beginner gaps, merge translations pages

[email protected] Mon, 22 Jun 2026 17:46:56 +0000
Newsgroups	gmane.comp.apache.cvs
Message-ID	<178215041670.1956686.10281711607798806536@gitbox3-he-fi.apache.org>
This is an automated email from the ASF dual-hosted git repository.

rbowen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/httpd-site.git


The following commit(s) were added to refs/heads/main by this push:
     new 6983a9c  docs-project: Deduplicate, fill beginner gaps, merge translations pages
6983a9c is described below

commit 6983a9c62234f5bf33b38bbe7e644b9a1de8abc2
Author: Rich Bowen <[email protected]>
AuthorDate: Mon Jun 22 13:46:28 2026 -0400

    docs-project: Deduplicate, fill beginner gaps, merge translations pages
    
    - index.md: Slim to a landing page with brief pointers to sub-pages;
      remove detailed sections that duplicated contribute.md
    - contribute.md: Add "Before You Start" (no ICLA needed, GitHub mirror
      is read-only, typical review turnaround) and "Fast Path for Small
      Fixes" (email/Bugzilla workflow for typos)
    - svn.md: Add "Repository Layout" directory map and "What's
      Auto-Generated?" note (.html, .xml.meta, allmodules.xml)
    - translations.md: Merge goingfurther.md content inline under
      #maintaining anchor
    - goingfurther.md: Replace with redirect stub
    - avail_translations.md: Update goingfurther.html link to
      translations.html#maintaining
---
 content/docs-project/avail_translations.md |  2 +-
 content/docs-project/contribute.md         | 21 +++++++
 content/docs-project/goingfurther.md       | 92 +----------------------------
 content/docs-project/index.md              | 80 ++++++-------------------
 content/docs-project/svn.md                | 32 ++++++++++
 content/docs-project/translations.md       | 95 +++++++++++++++++++++++++++---
 6 files changed, 161 insertions(+), 161 deletions(-)

diff --git a/content/docs-project/avail_translations.md b/content/docs-project/avail_translations.md
index 878102f..18d0486 100644
--- a/content/docs-project/avail_translations.md
+++ b/content/docs-project/avail_translations.md
@@ -9,7 +9,7 @@ see gaps in a language you speak, we'd welcome your contribution.
 
 To get started translating, see the [translation guide](translations.html).
 To learn about keeping translations up to date, see
-[Maintaining Translations](goingfurther.html).
+[Maintaining Translations](translations.html#maintaining).
 
 If you can provide translations into any of these languages (or any
 others not yet listed), please let us know on
diff --git a/content/docs-project/contribute.md b/content/docs-project/contribute.md
index 1a68d15..a2c8be5 100644
--- a/content/docs-project/contribute.md
+++ b/content/docs-project/contribute.md
@@ -12,6 +12,16 @@ This page is about *contributing to the docs*, not about configuring
 httpd. For configuration help, see the
 [Users mailing list](../userslist.html).
 
+## Before You Start
+
+- **No ICLA or ASF account is needed** to submit documentation patches.
+  Anyone can contribute.
+- **The GitHub mirror** (github.com/apache/httpd) is read-only — do NOT
+  open pull requests there. They won't be reviewed. Patches go through
+  SVN and the mailing list.
+- **Patches sent to the mailing list** are typically reviewed within a
+  few days.
+
 ## Ways to Contribute
 
 There's something for every skill level:
@@ -27,6 +37,17 @@ There's something for every skill level:
 - **Join the conversation** — Subscribe to `[email protected]` and
   weigh in on ongoing discussions.
 
+### Fast Path for Small Fixes
+
+You don't need SVN to report a problem or suggest a fix. For typos or
+small corrections, just describe the fix in an email to
+`[email protected]`, or open a Bugzilla ticket with the corrected
+text. A committer will apply it for you.
+
+For anything more than a sentence or two, the SVN patch workflow
+(described below) is preferred — it gives reviewers the full context of
+your change.
+
 ### Fix and Improve (SVN patch workflow)
 
 - Fix typos, broken examples, or unclear explanations.
diff --git a/content/docs-project/goingfurther.md b/content/docs-project/goingfurther.md
index 6404473..114ef00 100644
--- a/content/docs-project/goingfurther.md
+++ b/content/docs-project/goingfurther.md
@@ -1,92 +1,4 @@
-Title: Maintaining Translations
+Title: Maintaining Translations (Moved)
 license: https://www.apache.org/licenses/LICENSE-2.0
 
-# Maintaining Translations
-
-Once you've started translating, the ongoing work is keeping your
-translations up to date as the English source evolves. This page
-describes a practical workflow for tracking changes and updating your
-translated files.
-
-## The Basic Idea
-
-The English documentation changes over time — bugs get fixed, features
-get documented, examples get improved. As a translator, you need to:
-
-1. Detect which English files have changed since you last translated
-2. See what specifically changed
-3. Apply the equivalent changes to your translated files
-4. Verify your work builds correctly
-
-## Recommended Workflow
-
-### Set Up Your Working Environment
-
-Check out both active branches:
-
-    svn checkout https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs httpd-trunk
-    svn checkout https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x/docs httpd-2.4
-
-### Track Changes with SVN
-
-The simplest way to see what's changed since a known revision is
-`svn diff` between revisions. If you noted that you last synchronized
-your translation at revision 1900000, you can see all changes since then:
-
-    svn log -r 1900000:HEAD docs/manual/mod/mod_rewrite.xml
-    svn diff -r 1900000:HEAD docs/manual/mod/mod_rewrite.xml
-
-**Tip:** Note the current revision number each time you finish updating
-a translation. Add it as a comment at the top of your translated file:
-
-    <!-- English Revision: 1912345 -->
-
-This makes it easy to check what's changed next time:
-
-    svn diff -r 1912345:HEAD docs/manual/mod/mod_rewrite.xml
-
-### Update Your Translation
-
-With the diff output showing what changed in the English source, apply
-the equivalent changes to your translated file. Focus on:
-
-- New paragraphs or sections that need translating
-- Changed examples or directive descriptions
-- Removed content that should also be removed from your translation
-- Corrected technical information
-
-### Verify Your Work
-
-Build the docs to confirm your XML is valid and the output looks right:
-
-    cd docs/manual/build
-    ./build.sh validate-xml
-    ./build.sh <your-language-code>
-
-Open the generated HTML in a browser to review the final result.
-
-### Submit Your Updates
-
-Send your updated files as a patch:
-
-    svn diff > translation-update.patch
-
-Email the patch to `[email protected]`, or attach it to a
-[Bugzilla ticket](https://bz.apache.org/bugzilla/).
-
-## Staying in Sync
-
-A few habits that make maintenance easier:
-
-- **Update regularly** — small, frequent updates are much easier than
-  catching up after months of changes.
-- **Watch the commits list** — subscribe to the svn commits to see
-  documentation changes as they happen.
-- **Coordinate with other translators** — if there are multiple people
-  working on your language, divide the work and communicate via the
-  mailing list.
-
-## Questions?
-
-If you get stuck or have questions about maintaining translations, reach
-out to `[email protected]`. We're happy to help.
+This content has been merged into the [Translations](translations.html#maintaining) page.
diff --git a/content/docs-project/index.md b/content/docs-project/index.md
index 3470c43..ed11ac6 100644
--- a/content/docs-project/index.md
+++ b/content/docs-project/index.md
@@ -12,53 +12,20 @@ You don't need to be a programmer. You don't need to be an httpd expert.
 If you can read the docs and spot something that could be clearer, you're
 already qualified to contribute.
 
-## Quick Links
-
-- [Report a problem](#report)
-- [Make a suggestion](#suggestion)
-- [Contribute to the docs](#contribute)
-- [Translate the documentation](#translate)
-- [Find the docs](#docs)
-- [Join the mailing list](#ml)
-- [Chat with us on IRC](#irc)
-
-## Report a Problem {#report}
-
-Found something wrong? The best way to report it is to [open a
-Bugzilla ticket](https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=Documentation)
-with "Documentation" selected as the component.
-
-You can also check the [list of open documentation
-bugs](http://s.apache.org/httpd-doc-bugs) to see if it's already known.
-
-## Make a Suggestion {#suggestion}
-
-Have an idea for how we could explain something better? Want to propose
-a new how-to or tutorial?
-
-The best approach is to [join the mailing list](#ml) and start a
-conversation. You can also [open a Bugzilla ticket](#report) with your
-suggestion. Either way, we're glad to hear from you.
-
-## Contribute {#contribute}
-
-Ready to dive in? Our [contribution guide](contribute.html) walks you
-through the different ways to help — from quick fixes to substantial new
-content. The workflow uses SVN and patches, and we have a
-[step-by-step SVN guide](svn.html) to get you started.
-
-New to the XML format we use? That's fine — take a look at the
-[documentation format](docsformat.html) page, and don't hesitate to ask
-questions on the mailing list. We're happy to help you get oriented.
-
-See also: [Tools for Contributors](tools.html) for editor and workflow
-recommendations.
-
-## Style Guide {#style}
-
-When writing or editing documentation, please follow the conventions in
-our [Documentation Style Guide](style-guide.html). It covers markup,
-prose style, and formatting standards.
+## Get Involved
+
+- **[Contribute to the docs](contribute.html)** — report problems, suggest
+  improvements, fix errors, or write new content.
+- **[Translate the documentation](translations.html)** — help make the docs
+  accessible to non-English speakers.
+- **[SVN workflow](svn.html)** — check out the source and submit patches.
+- **[Documentation format](docsformat.html)** — learn the XML format used
+  for the docs.
+- **[Style guide](style-guide.html)** — markup and prose conventions.
+- **[Tools for contributors](tools.html)** — editor and workflow
+  recommendations.
+- **[Contributors](contributors.html)** — the people who built these docs
+  (we hope to add your name here soon).
 
 ## The Mailing List {#ml}
 
@@ -73,24 +40,13 @@ You can browse current and past messages at
 If you're not subscribed, your messages may still be moderated through
 if they're on-topic.
 
-## Translate the Documentation {#translate}
-
-The documentation is available in several languages, but many
-translations are incomplete or out of date. If you're fluent in a
-non-English language, we'd welcome your help. See our
-[translation guide](translations.html) to get started, and check the
-[translation status](avail_translations.html) to see what's needed.
+## IRC {#irc}
 
-Please [introduce yourself on the mailing list](#ml) before you begin so
-other translators can coordinate with you.
+You can find us in **#httpd** on [irc.libera.chat](https://libera.chat/).
+Drop in if you have quick questions or want to chat with other
+contributors in real time.
 
 ## Where Are the Docs? {#docs}
 
 - [Version 2.4](../docs/2.4/) (current stable release)
 - [Trunk / Development](../docs/trunk/) (next version in progress)
-
-## Contributors
-
-The Apache HTTP Server documentation is the product of many people's
-work over many years. See the [contributors page](contributors.html)
-for the full list — and we hope to add your name there soon.
diff --git a/content/docs-project/svn.md b/content/docs-project/svn.md
index 6804bec..bfb83f8 100644
--- a/content/docs-project/svn.md
+++ b/content/docs-project/svn.md
@@ -37,6 +37,38 @@ to the checkout URLs:
 This gives you a lighter checkout, though you won't have the full source
 tree for context.
 
+## Repository Layout
+
+Once you have a checkout, you'll find the documentation source under
+`docs/manual/`. Here's what lives where:
+
+- **`mod/`** — module reference pages (one `.xml` per module)
+- **`howto/`** — tutorial-style how-to guides
+- **`vhosts/`** — virtual host documentation
+- **`rewrite/`** — mod_rewrite guide and recipes
+- **`misc/`** — miscellaneous reference pages
+- **`faq/`** — frequently asked questions
+- **`ssl/`** — SSL/TLS documentation
+- **`programs/`** — httpd support programs documentation
+- **`style/`** — DTD, XSL, CSS (build system — don't edit unless you
+  know what you're doing)
+- **`.xml` files** — the source you edit
+- **`.xml.meta`** — auto-generated metadata (don't edit)
+- **`.html.*` files** — auto-generated HTML output (don't edit)
+
+### What's Auto-Generated? {#autogenerated}
+
+Several file types in the tree are build output — never edit these
+directly:
+
+- **`.html` and `.html.*` files** — generated HTML output for each
+  language. These are rebuilt from the `.xml` source.
+- **`.xml.meta` files** — generated by the build system to track
+  translation status and revision info.
+- **`allmodules.xml`** — auto-generated when adding new modules.
+
+**Only edit `.xml` source files.** Everything else is derived from them.
+
 ## Creating a Patch
 
 Once you have a checkout, the process is:
diff --git a/content/docs-project/translations.md b/content/docs-project/translations.md
index 04fb23e..eb2f2c2 100644
--- a/content/docs-project/translations.md
+++ b/content/docs-project/translations.md
@@ -74,12 +74,6 @@ Send your completed file (or a patch) to `[email protected]`. A
 committer will review it and add it to the repository. Over time, you
 may gain commit access yourself.
 
-## Keeping Translations Current
-
-Once your initial translation is committed, you'll want to keep it up to
-date as the English source evolves. See
-[Maintaining Translations](goingfurther.html) for a practical workflow.
-
 ## Review Standards
 
 Because the development team can't easily verify non-English content, we
@@ -97,11 +91,96 @@ We encourage you to place credits in a comment at the top of the file:
 The build system tracks the SVN revision of the equivalent English
 version, so future translators know where to start updating.
 
+## Maintaining Translations {#maintaining}
+
+Once your initial translation is committed, the ongoing work is keeping
+it up to date as the English source evolves. Here's a practical workflow
+for tracking changes and updating your translated files.
+
+### The Basic Idea
+
+The English documentation changes over time — bugs get fixed, features
+get documented, examples get improved. As a translator, you need to:
+
+1. Detect which English files have changed since you last translated
+2. See what specifically changed
+3. Apply the equivalent changes to your translated files
+4. Verify your work builds correctly
+
+### Set Up Your Working Environment
+
+Check out both active branches:
+
+    svn checkout https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs httpd-trunk
+    svn checkout https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x/docs httpd-2.4
+
+### Track Changes with SVN
+
+The simplest way to see what's changed since a known revision is
+`svn diff` between revisions. If you noted that you last synchronized
+your translation at revision 1900000, you can see all changes since then:
+
+    svn log -r 1900000:HEAD docs/manual/mod/mod_rewrite.xml
+    svn diff -r 1900000:HEAD docs/manual/mod/mod_rewrite.xml
+
+**Tip:** Note the current revision number each time you finish updating
+a translation. Add it as a comment at the top of your translated file:
+
+    <!-- English Revision: 1912345 -->
+
+This makes it easy to check what's changed next time:
+
+    svn diff -r 1912345:HEAD docs/manual/mod/mod_rewrite.xml
+
+### Update Your Translation
+
+With the diff output showing what changed in the English source, apply
+the equivalent changes to your translated file. Focus on:
+
+- New paragraphs or sections that need translating
+- Changed examples or directive descriptions
+- Removed content that should also be removed from your translation
+- Corrected technical information
+
+### Verify Your Work
+
+Build the docs to confirm your XML is valid and the output looks right:
+
+    cd docs/manual/build
+    ./build.sh validate-xml
+    ./build.sh <your-language-code>
+
+Open the generated HTML in a browser to review the final result.
+
+### Submit Your Updates
+
+Send your updated files as a patch:
+
+    svn diff > translation-update.patch
+
+Email the patch to `[email protected]`, or attach it to a
+[Bugzilla ticket](https://bz.apache.org/bugzilla/).
+
+### Staying in Sync
+
+A few habits that make maintenance easier:
+
+- **Update regularly** — small, frequent updates are much easier than
+  catching up after months of changes.
+- **Watch the commits list** — subscribe to the svn commits to see
+  documentation changes as they happen.
+- **Coordinate with other translators** — if there are multiple people
+  working on your language, divide the work and communicate via the
+  mailing list.
+
+## Questions?
+
+If you get stuck or have questions about translating or maintaining
+translations, reach out to `[email protected]`. We're happy to help.
+
 ## Related Information
 
 - [Documentation Format](docsformat.html) — the XML format and how to
   build HTML from it
 - [Translation Status](avail_translations.html) — what's been
   translated and what's needed
-- [Maintaining Translations](goingfurther.html) — keeping your work
-  up to date