Godot-docs: Approaching Documentation with a wider audience in mind

[golddotasksquestions]

Godot version:
3.0, 3.1

OS/device including version: all

Issue description:
A supposed "lack" of documentation has become a meme within the community. As it has been discussed on Reddit multible times, I'm opening up this issue as a place to discuss, comment and keep track of progress.
General consensus seems to be, that as Godot grows, so does the documentation audience. Therefore a form of documentation is needed which is comprehensible for people from all areas of development, not just people with existing programming background. The Gamemaker documentation has also been mentioned a few times as a good example of archiving exactly that and could be used as a general guide in terms of structure.

[NathanLovato]

The docs guidelines are already designed with a wide audience in mind. Over time it's gotten a lot more complete and accessible.

There's always room for improvement, but not enough hands to handle the huge workload. We lack involved contributors with different skills and perspectives. People who will take time to write detailed feedback, simplify the language, contribute accessible code examples...

Review, proofing, and editing are essential in any writing work if you want a great result. It's as much work as writing the content in the first place. There are contributors helping with this, just not enough right now.

Firstly, I'd separate the discussion between the manual (tutorials and guides) and the code reference into two issues. The reference is a tool for developers so the audience isn't going to be exactly the same as the manual: a fair number of tutorials and articles are for artists, designers... people who won't code in the team.

Note we have writing guidelines to help write consistent and accessible English, but getting people to follow them can be a challenge. Sometimes it's better to merge new, needed content first and proof later, when nobody is around to do a full review: http://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html

The reference

The reference needs work to unify, clarify, and simplify existing docstrings following some fairly strict guidelines. It could also use some more code snippets. But the ref is going to be a bit technical whatever happens. You can't cut on some technical words, although sure, whenever possible, we should favor plain English. But you'll need people who have programming knowledge to contribute here.

The manual

When it comes to the manual, we need:

• Writers who aren't necessarily developers to do copy work. People who will edit existing entire sections of pages to refine the form, the layout, make tutorials more accessible
• Users who will take the time to write detailed feedback. Both negative and positive. Detail their experience with tutorials, how they feel reading the pages, if anything confused them, where they hit roadblocks, what they tried at this point... But also positive feedback: what worked well, what was clear, which layout is easiest on the eyes, everything we could use to improve the guidelines and consistency in the manual moving forward.
• More events/meetups/online jams to get people together to work on the docs. One common issue with consistency is people working on their thing alone, not getting any review until they've done the work, not communicating their intention to work on something...
• And people to document the undocumented. We're going to do a "new features in Godot 3.1" series at GDquest, and two workshop series for the official docs. It'd be nice to have other teams coordinate to work on projects like these, be it together or in parallel.

[willnationsdev]

@NathanLovato

• Users who will take the time to write detailed feedback.

I find it historically more likely for people to give feedback of this sort when there is an immediate request for feedback on the page itself and an immediate availability of communication outlets for users.

Could we perhaps setup an email for Godot that pertains exclusively to docs feedback and then put a little widget in the bottom-right of the docs site that says something like, "Want to give feedback?" If they click on it, it could then open up their email client with the email addresses setup and ready to go. I wouldn't suspect that would require a lot of changes to the website tools (though I don't have any experience in that area, so idk).

It would be even better if it would just open up a miniature modal form where they can type in their name, it would prepopulate with the page they are on for reference, and then they could type out a description of their feedback which the form then generates an email template from and sends all the data off to us.

[golddotasksquestions]

@NathanLovato
Where do I "provide feedback"?
For instance right now I'm looking for the right input event for my button press going through this list:
https://docs.godotengine.org/en/3.0/classes/class_input.html#class-input-action-press
I would like to understand what action_press() does but the docs are not helpful - at all. There is no contact at the end of the page. I would like to leave a note saying that I don't understand this part, or that I think it needs clarification, an example or more detailed description. Am I expected to open an issue for all these cases? Because this would result me in doing nothing else but researching and writing issues.

[NathanLovato]

@golddotasksquestions It depends on the feedback. If you can fix it by yourself, you can create a pull request following the docs writing guidelines. That's the best way to help improve the docs directly. In general, you should open an issue, give as much details as possible, and use labels if any applies.

You can group feedback per category or related topics (e.g. Input) in a single issue and give people a checklist, use markdown to format your post and make it easier to track.

[Pobega]

One interesting thing I noticed about Unity's documentation is that on some pages, at the top of the page they include a "Switch to Manual" button. It may alleviate these issues if the Class Reference stuff linked back to some pre-existing higher-level tutorial in some way.

See: https://docs.unity3d.com/ScriptReference/AnimationClip.html

[willnationsdev]

@Pobega actually, there is a section of the XML files, from which the docs are generated, that specifically gives users the opportunity to provide links to relevant online documentation. For example, the Input class shows the "Inputs" tutorial link in its API page.

[Pobega]

@willnationsdev is that in 3.0? Because I don't see it here: https://docs.godotengine.org/en/3.0/classes/class_input.html

(and apologies, I don't know where to find the 3.1 documentation or I'd check myself, a quick Google turned up nothing)

[willnationsdev]

@Pobega Use the 'latest' URL, not '3.0'. "Tutorials" header of the page.
https://docs.godotengine.org/en/latest/classes/class_input.html#tutorials

[Pobega]

Perhaps there should be some consideration making the link a bit more prevalent (similar to the 'Edit On Github' link at the top) so that it's consistent between pages

[willnationsdev]

@Pogeba ohhhh, that's a good idea!

[mhilbrunner]

A supposed "lack" of documentation has become a meme within the community

I wouldn't say a single Youtube video with 3k views and a reddit thread with 22 comments makes a (community-wide, reoccuring) meme.

The documentation can certainly always be improved further. Still, feedback is mixed at worst; quite a few people like the docs (even in the comments on that Youtube video).

I think the fundamental issue is...

not just people with existing programming background.

I'd argue that is mostly outside of the scope of Godot and it's docs.

We simply can't teach you programming, and personally I'd heavily advise against learning programming, game development and using a general purpose game engine like Godot all at the same time.

Seriously, creating a working, marketable webapp/-site or app is already quite hard if you don't know much about programming, adding all the challenges of game development on top is... hard.

We just don't have the resources, as nice as it would be. :)

I'm closing this, see the proposal below for very related discussion:
https://github.com/godotengine/godot-docs/issues/3390

[golddotasksquestions]

This issue was opened more than a year ago, and I would argue the documentation has improved quite a bit since then. For instance the API docs for the most frequently used nodes now have a proper description, some even example code and links to a the step by step tutorials.

However I'm not happy at all you closed this issue @mhilbrunner

This issue is not about making the documentation complete (that's really a no brainer, and there is ample progress being made). This issue is about the fact that game development is a multi disciplinary endeavor. What follows, imho, is that people from different background should be able to learn how to use Godot.

Godot is not so complicated that only experience programmers can understand how to use it. Neither is learning programming with GDScript. In fact, I'd even say GDScript might be the easiest introduction to OOP I can think of. At least for someone like me who has an affinity for games it might very well be.

I'm saying this also as someone who started learning Godot and GDScript without any programming experience and only very little hands on experience with other game engines.

What is complicated however is how the documentation, the step by step, and some tutorials are worded and phrased. It uses a language that makes sense to people who already come into this with programming background.

Why? Why this limitation? Why this discrimination?

No one expects a game engine documentation to be a substitute for a programming tutorial.
But as it is right now, much of the step by step is impossible to follow for someone without years of programming experience elsewhere or years of experience with Godot.

I think the issue here is still present, and therefore it should not be closed. I realize this won't change over night, if ever, it will take years. But it would be nice if the documentation community would open up to the idea of more approachable language.

[willnationsdev]

@golddotasksquestions

I would venture to say that the concerns you've raised here have been mirrored in the proposal that mhilbrunner linked. The discussion mentions a desire to create alternate tracks of introductory tutorials for Godot: one that is gentler for people new to programming overall and one that is an overview for helping experienced users get accustomed to Godot. It also suggests having one 2D and one 3D introductory tutorial. In addition, people have mentioned simplifying the user interface to more directly grab new users' attention and direct them to the resources that are most relevant to them so that they don't get lost in everything that's there.

From the discussion in that proposal, the documentation community appears to recognize the need for more approachable content/language, and wishes to create distinct spaces for that. As such, I believe that the content of this proposal is more or less superceded by Nathan Lovato's as it clarifies how best to actually implement the changes that you have requested here, among other things.

[mhilbrunner]

@golddotasksquestions

The tutorials are written by people trying to educate - for free I might add.
Nobody has any interest in discriminating anyone.
No one is trying to gatekeep by creating deliberately hard-to-follow tutorials.

If you spot anything where you think something could be more clear, you're very welcome to open specific Pull Requests or Issues to improve those parts.

Note that not all contributors to the docs are teachers or skilled writers in addition to being good programmers. Also, not all of them are native speakers.

However, having a jargon, or inside language in a field is a useful thing, even if it seems daunting or an artificial barrier to entry. Being able to communicate complicated concepts easily and efficiently is very useful.

You would probably not expect to be able to read and understand a medical text without either prior knowledge or quite some research; likewise for an airplane or industrial tool manual.

Still, in your original issue:

Therefore a form of documentation is needed which is comprehensible for people from all areas of development, not just people with existing programming background.

I agree that that would be cool to have. I question that the official docs team is willing and able to create that.

I maintain my opinion that creating comprehensive docs that are understandable to people without programming background or teaching programming are outside the scope of the docs.

Even maintaining the current state of the docs has proven to be too much maintenance burden.

You are free to disagree, of course. But I still think having this discussion in a central place is better, so again, I suggest https://github.com/godotengine/godot-docs/issues/3390 :)

No ill will intended. :)

[golddotasksquestions]

@mhilbrunner
I reply here if you don't mind.
I fully agree with you with pretty much all of your points. Especially about jargon being a useful thing, and an aid in communication. Absolutely! (Between professionals who both speak the jargon)

However dumping a shitload of Jargon on someone just entering the door who does not speak the language is the opposite of being inclusive. It _is_ in fact gatekeeping. (though I never assumed or suggested this to be intentional).

You can explain ideas functionality and principles without jargon. Yes I know it's effort and not everyone is good at it. But I opened this issue to describe a need to aim for that direction.

If you have the time, take a quick look at this clip from 1937 that explains how the differential in cars works and maybe also have a look at the comments:
https://www.youtube.com/watch?v=yYAw79386WI

These 11million viewers all engineers? I don't think so.

[mhilbrunner]

I think we mostly agree, but the docs need to be maintainable by the docs team. It's already a lot of work :)