Merge pull request #30 from sn3rd/main

Add a new page inviting contributions to Launchpad documentation

.sphinx/spellingcheck.yaml

@@ -9,7 +9,7 @@ matrix:
     - .custom_wordlist.txt
     output: .sphinx/.wordlist.dic
   sources:
-  - _build/**/*.html|!_build/explanation/hacking/index.html|!_build/help/index.html|!_build/how-to/database-setup/index.html|!_build/how-to/submitting-a-patch/index.html|!_build/how-to/database-schema-changes-process/index.html|!_build/how-to/triage-bugs/index.html|!_build/explanation/registry/index.html|!_build/explanation/css-sprites/index.html|!_build/explanation/working-with-db-devel/index.html|!_build/explanation/pre-merge-reviews/index.html|!_build/explanation/live-patching/index.html|!_build/explanation/css/index.html|!_build/explanation/javascript-unittesting/index.html|!_build/explanation/engineering-overview-translations/index.html|!_build/explanation/testing/index.html|!_build/explanation/feature-flags/index.html|!_build/explanation/launchpad-ppa/index.html|!_build/explanation/branches/index.html|!_build/explanation/code/index.html|!_build/explanation/security-policy/index.html|!_build/explanation/database-performance/index.html|!_build/explanation/url-traversal/index.html|!_build/explanation/navigation-menus/index.html|!_build/explanation/storm-migration-guide/index.html|!_build/explanation/mail/index.html|!_build/explanation/javascript-buildsystem/index.html|!_build/explanation/javascript-integration-testing/index.html
+  - _build/**/*.html|!_build/explanation/hacking/index.html|!_build/help/index.html|!_build/contribute-to-our-docs/index.html|!_build/how-to/database-setup/index.html|!_build/how-to/submitting-a-patch/index.html|!_build/how-to/database-schema-changes-process/index.html|!_build/how-to/triage-bugs/index.html|!_build/explanation/registry/index.html|!_build/explanation/css-sprites/index.html|!_build/explanation/working-with-db-devel/index.html|!_build/explanation/pre-merge-reviews/index.html|!_build/explanation/live-patching/index.html|!_build/explanation/css/index.html|!_build/explanation/javascript-unittesting/index.html|!_build/explanation/engineering-overview-translations/index.html|!_build/explanation/testing/index.html|!_build/explanation/feature-flags/index.html|!_build/explanation/launchpad-ppa/index.html|!_build/explanation/branches/index.html|!_build/explanation/code/index.html|!_build/explanation/security-policy/index.html|!_build/explanation/database-performance/index.html|!_build/explanation/url-traversal/index.html|!_build/explanation/navigation-menus/index.html|!_build/explanation/storm-migration-guide/index.html|!_build/explanation/mail/index.html|!_build/explanation/javascript-buildsystem/index.html|!_build/explanation/javascript-integration-testing/index.html
   pipeline:
   - pyspelling.filters.html:
       comments: false

contribute-to-our-docs.rst

@@ -0,0 +1,53 @@
+Contribute to our docs
+======================
+
+We are committed to continuously improving our documentation and making it 
+more useful for both ourselves and others.
+
+**We warmly welcome community contributions, suggestions, fixes, and 
+constructive feedback.**
+
+To contribute, go ahead and submit an issue or pull request at 
+https://github.com/canonical/launchpad-manual.
+
+If you have any questions or doubts, please don't hesitate to 
+reach out to us by any of these means:
+
+- Join the `#launchpad IRC channel`_ at `irc.libera.chat`_ and ask your
+  questions.
+- Ask a question: https://answers.launchpad.net/launchpad
+- Send an e-mail to [email protected]
+
+Style and language
+++++++++++++++++++
+
+Launchpad's documentation is aimed at helping both beginners and experts. As 
+such, we try to use appropriate writing for the subject, to use inclusive 
+language, and to assume that the reader has as little prior knowledge as 
+possible.
+
+The nativation, structure, style, and content of our documentation follows the 
+`Diátaxis`_ systematic framework for technical documentation authoring. This 
+splits pages into tutorials, how-to guides, reference material, and 
+explanatory text.
+
+Some general tips that could help to ensure high quality documentation:
+
+- use a spell checker
+- resist being overly formal
+- resist being overly verbose
+- verify links and examples 
+
+We recommend using the `Ubuntu style guide`_.
+
+Feel free to suggest changes to any documentation topic with updated or more 
+insightful information. We aim for consistency, but don't let formality 
+prevent you from contributing. If something is inconsistent, we'll fix it. 
+We'd rather have documentation that we can fix than not have documentation at 
+all.
+
+.. _#launchpad IRC channel: irc://irc.libera.chat/launchpad
+.. _irc.libera.chat: irc.libera.chat
+.. _API documentation: http://people.canonical.com/~mwh/canonicalapi/
+.. _Diátaxis: https://diataxis.fr/
+.. _Ubuntu style guide: https://docs.ubuntu.com/styleguide/

custom_conf.py

@@ -115,6 +115,7 @@
     'https://archive.ph/CAqQm',  # ignore, as works in browser, but link checker has some issues
     'https://bazaar.launchpad.net/lp-production-config',  # private
     'https://bazaar.staging.launchpad.net',  # broken, unclear why XXX 2023-10-14: jugmac00- check with team
+    'https://www.breezy-vcs.org', # broken, returns "Connection refused" on port 443
     'https://bugs.launchpad.net/charm-launchpad-buildd-image-modifier',  # private
     'https://bugs.launchpad.net/launchpad-vbuilder-manage',  # private
     'http://example.com/.*',  # ignore, example links

how-to/index.rst

@@ -4,6 +4,8 @@ How-to Guides
 Getting started
 ---------------
 
+To get started with Launchpad, get the source code and run a local development instance.
+
 .. toctree::
    :maxdepth: 1
 
@@ -14,48 +16,48 @@ Getting started
 Common development tasks
 ------------------------
 
+Once you have an instance of Launchpad, you're ready to contribute!
+
 .. toctree::
    :maxdepth: 1
 
+   submitting-a-patch
    fixing-bugs
    contributing-changes
-   submitting-a-patch
-   exceptions
-   security
-   using-breakpoints
-   preserve-query-count
-   land-update-for-loggerhead
-   update-configuration-for-testing
-   testing-scripts
-   create-job-publish-artifact
-   chameleon
+   use-updated-dependency
    database-schema-changes-process
+   apply-schema-changes
+   importing-an-ubuntu-package
 
-Common operational tasks
-------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   triage-bugs
+Launchpad development tips
+--------------------------
 
-Operating development instances
--------------------------------
+There are some things that can make your journey of contributing to Launchpad much easier.
 
 .. toctree::
    :maxdepth: 1
 
-   new-user
-   apply-schema-changes
-   use-updated-dependency
-   importing-an-ubuntu-package
+   update-configuration-for-testing
+   using-breakpoints
+   security
+   testing-scripts
+   exceptions
+   preserve-query-count
+   chameleon
 
-Operating Canonical's instances
--------------------------------
+Operating Launchpad
+------------------------
+
+If you have a running instance of Launchpad, there are common tasks you might need to perform.
 
 .. toctree::
    :maxdepth: 1
 
-   deploying-configuration-changes
-   checking-availability-of-launchpad-frontends
    getting-overview-of-build-farm
+   checking-availability-of-launchpad-frontends
+   new-user
+   create-job-publish-artifact
+   triage-bugs
+   deploying-configuration-changes
+   land-update-for-loggerhead
+

index.rst

@@ -59,7 +59,8 @@ contributions, suggestions, fixes and constructive feedback.
 
 * `Code of conduct <https://ubuntu.com/community/ethos/code-of-conduct>`_
 * :doc:`Get support <help>`
-* :doc:`Contribute <how-to/contributing-changes>`
+* :doc:`Contribute to our code <how-to/contributing-changes>`
+* :doc:`Contribute to our docs <contribute-to-our-docs>`
 
 .. toctree::
    :hidden:
@@ -70,3 +71,4 @@ contributions, suggestions, fixes and constructive feedback.
    reference/index
    explanation/index
    help
+   contribute-to-our-docs