Add a new page inviting contributions to Launchpad documentation #30
Conversation
…king this from the navigation menu
Re-group how-to's Add an introductory sentence per category Re-order list items Add a linkcheck_ignore item for www.breezy-vcs.org which is not reachable.
There was a problem hiding this comment.
Thanks a lot! This looks great!!!
A couple of comments, mostly inline.
Usually, we wrap the text after ~80 characters, which make it easier to read and manage, even when you could emulate that in the editor with "Word Wrap" or similar functions.
This is afaik neither documented nor enforced by linters, which we def. should do.
The link to this new guide on the left is easily overlooked.
I would suggest to additionally update https://github.com/canonical/launchpad-manual/blob/main/index.rst#project-and-community section, where we already have a contribution link for code, e.g. "Contribute to code / Contribute to documentation." - and make both terms a link.
| @@ -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 | |||
There was a problem hiding this comment.
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.
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.
contribute-to-our-docs.rst
Outdated
| - Ask a question: https://answers.launchpad.net/launchpad | ||
| - Send an e-mail to [email protected] | ||
|
|
||
| Or go ahead and submit an issue or pull request at https://github.com/canonical/launchpad-manual. |
There was a problem hiding this comment.
Personally, I would prefer to have people create issues in the very first place, as this feels more coherent, as the documentation is also hosted here on GitHub.
There was a problem hiding this comment.
Good point; will amend.
|
|
||
| Some general tips: | ||
|
|
||
| - 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".
| - use a spell checker | ||
| - 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.
Update the "Project and community" section to have links to contribute to both code and docs Make the call to action to log issues on GitHub stronger, and emphasise discussion via other channels Position the general tips as a helpful way to ensure better quality documentation Re-arrange some content to flow a bit better
No description provided.