-
Notifications
You must be signed in to change notification settings - Fork 16
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a new page inviting contributions to Launchpad documentation #30
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We have a linter for that, so at one point we probably should suggest to use tooling, though I do not want anybody to be kept off from contributing when they do not feel comfortable to use make files. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Makes sense; will address with an amendment based on the other comment about changing to "could". |
||
- resist being overly formal | ||
- resist being overly verbose | ||
- verify links and examples | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe we could add a line that people "could" use make file to ensure high standards. |
||
|
||
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/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Excluding some converted pages from spellchecking was a means to an end to get the migration done in time.
We should not make it a habit to exclude newly written pages.
You can add new words to the
.custom_wordlist.txt
configuration file.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I actually did this, and it didn't work as I expected, so I ended up adding the exclusion in order to move on. I think we should have a separate exercise to fix this up.