godotengine / godotengine/godot-docs

Prevent recursive definitions or repeating names over context in class reference documentation

Open
#11,855 0 comments 2 reactions 0 assignees View on GitHub
area:class reference enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

### Problem or limitation

when browsing the class references to unfamiliar tools in Godot, more often than i'm comfortable with i stumble upon method descriptions like this:

```xml






Returns the human-readable description of the given action.

```

where in this example, if you don't have a context of what "human-readable description" entails, you might as well understand this single sentence as the method name copy-pasted as the description, sometimes vague enough to a point where looking at the engine code itself gives a better description than that sentence, and for me this can get frustrating when i don't know much c++.

### Proposed improvement

include in the documentation contribution guidelines, a dedicated section describing ways to avoid non descriptive repetitions of names of elements.

documentation needs to always assume the reader had never read anything before that particular page, and repeating context can be much more helpful than repeating names only. the exercise to practice for this is in trying to make a conscious effort in defining a word, but without using the word itself, and without jumping into examples without fully defining it first.

another example also from InputMap.xml:

```xml




Returns a deadzone value for the action.

```

the above should then become this:

```xml




Returns the current, minimum percentage value for the analog threshold of the given [code]action[/code] in which it activates. Analog input strengths below that value will not activate.

```

it is more verbose, but is easier to understand if someone happens to encounter the concept of a deadzone for the first time in the documentation, and i should say the same about lots of words used in the engine as a whole that can and will get exposed to even people learning programming for the first time, let alone people who can program but are encountering other field vocabularies in it.

### Proposal review

- [x] Yes, this proposal is highly specific and actionable.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.