Add a new page inviting contributions to Launchpad documentation #30
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. 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. 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. 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/ | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.txtconfiguration 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.