Write content guidelines #4064
Write content guidelines #4064
Conversation
|
Where should we link to and recommend tools for spell and grammar checking? Also, should we only link to open-source software, or is it fine to include a service like Grammarly? I'm asking because e.g. languagetool can be difficult to set up locally and it's far from offering as many recommendations as AI-powered technology. Unfortunately, though, I don't know any open-source alternative that comes close. |
NathanLovato
force-pushed
the
content/content_guidelines
branch
from
c53ce4d to
b61d936
Compare
|
I think we can safely link to any free tool that won't pollute contributor's machine or require them to give up some personal data. Like, it is important that we don't put this as a requirement for contributing to Godot. As far as tools go, it all depends on the editor our contributors use. I for one use VSCode for the docs and have some success with the SpellRight extension. Not that I've tested many, but it helped me to check grammar a bit better. |
|
Hence the question, grammarly is a machine-learning based service, they certainly collect and process your text data. I just mean to link to good optional tools that can help check your writing. The thing with spell checkers is they mostly report typos. Prose linters may highlight the passive voice for instance, which is a good addition. But AI-powered tools can go a step further and make recommendations regarding clarity, writing style, reordering sentences, and also tell you if a word or expression makes sense in context. I wish we had an open-source option for that. |
NathanLovato
force-pushed
the
content/content_guidelines
branch
2 times, most recently
from
0e325f1 to
0008899
Compare
|
|
||
| When adding or updating an engine feature, the documentation team needs to | ||
| know about it. Contributors should open an issue on the godot-docs repository | ||
| when their work gets merged and requires documentation. |
There was a problem hiding this comment.
I'd also suggest that the contributor should provide an overview of their work, those writing the documentation shouldn't have to troll through source code to figure out how functions work.
There was a problem hiding this comment.
Indeed. They're also welcome to write documentation themselves (and some do), but since not all devs are good technical writers it's good to have a workflow which enables them to provide technical insights in the new feature for others to write the docs.
That being said this section is about content guidelines, and details on what engine contributors should do to get their features properly documented might be better suited in the engine contribution guidelines (which are being rewritten in #4067, and might be further updated as we're discussing clarifications to the code contribution workflow with core engine devs).
|
|
||
| .. note:: | ||
|
|
||
| This principle does not mean we have to assume no prior programming |
Improve phrasing, grammar, fix indentation Co-authored-by: Rémi Verschelde <rverschelde@gmail.com> Co-authored-by: balloonpopper <5151242+balloonpopper@users.noreply.github.com>
- Removed typographic marks in the entire repo - Removed a line about why we don't use a wiki - Indented notes with 4 spaces - Addressed review comments
NathanLovato
force-pushed
the
content/content_guidelines
branch
from
6b416d9 to
9df8c5c
Compare
|
Thanks for your time reviewing and making suggestions! |
Some principles and guidelines to help assess what we should include in the docs.
It's inspired by the VueJS principles recommended by @Calinou.
Closes #4063