-
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
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point; will amend.
|
||
Some general tips: | ||
|
||
- use a spell checker |
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.
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 comment
The 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".
- use a spell checker | ||
- 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 comment
The 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.
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.