Godot-proposals: Use new financial resources to improve documentation

[Feniks-Gaming]

Describe the project you are working on:

Applicable to any game. I am currently working on card based tower defence.

Describe the problem or limitation you are having in your project:

Documentation has come leaps and bounds since Godot 3.0 days. We are on something like 95% complete for documentation but this still means that 1 in 20 descriptions doesn't exist. At this point what is left are things that aren't easy to document for casual contributors. In addition to that documentation is written by many different people, often with limited educational experience, and on many occasions non native English speakers. This results in sometimes not ideal descriptions and unclear explanation that use a lot of jargon and assumptions about users preexisting knowledge.

Describe how this feature / enhancement will help you overcome this problem or limitation:

With new resources from Epic grant Godot has now rare opportunity to use the resources to employ technical writer to oversee documentation. Someone with technical experience of writing clear documentation would be great addition to the team even if it's just part time job ensuring necessary standards and going through existing documentation in order to bring it to modern standard.

Show a mock up screenshots/video or a flow diagram explaining how your proposal will work:

I believe that a standard of documentation we should be aiming at is jargon free Game Maker Studio docs https://docs2.yoyogames.com/

Describe implementation detail for your proposal (in code), if possible:

No code required just person overseeing documentation.

If this enhancement will not be used often, can it be worked around with a few lines of script?:

All the time and has a long term benefit of being easier to keep up to date.

Is there a reason why this should be core and not an add-on in the asset library?:

It helps everyone.

[Xrayez]

I guess most of funds will be actually directed towards improving rendering features anyway, at least that's what I've seen from the news article:

Godot applied for a $250k usd grant for the category of open source graphics software, (which does not have the necessary requirement to be related to Unreal Engine), and expressed the wish to use the grant to improve graphics rendering as well as our built-in- game development language, GDScript.

Is there such a thing as a documentation writer being paid? Legit curious. :eyes:

I guess @NathanLovato would be the first candidate as a documentation writer, who'd also keep the class ref up-to-date. That also means figuring out how things works in the engine. Also @kidscancode.

We are on something like 95% complete for documentation but this still means that 1 in 20 descriptions doesn't exist.

Also expect that new features are part of 4.0 bandwagon, so we can expect 20% of undocumented new features.

---

Use new resources... title is misleading, I thought you proposed something akin to reusing Resource classes for documentation or something. 🙂

[Calinou]

Is there such a thing as a documentation writer being paid? Legit curious. :eyes:

That seems to be common in larger software development companies. I'm pretty sure companies like Microsoft have dozens, if not hundreds of people doing this full-time :wink:

[Sslaxx]

@reduz has discussed paid work packages; documentation sounds like it'd qualify for this.

[Feniks-Gaming]

I changed the title to better reflect what I am talking about. And yes Technical writer is actual job and we need those in charge.

A technical writer is a professional information communicator whose task is to transfer information (knowledge) between two or more parties, through any medium that best facilitates the transfer and comprehension of the information. Technical writers research and create information through a variety of delivery media (electronic, printed, audio-visual and even touch).[1] Example types of information include online help, manuals, white papers, design specifications, project plans and software test plans. With the rise of e-learning, technical writers are increasingly becoming involved with creating online training material.

While Nathan and Kids can Code are good teacher it takes different skill set to translate knowledge into written form than it takes to show it in a video. We need someone in charge that knows what they are doing and has prior experience in writing documentation.

[follower]

FWIW I do think by some definitions "improve [...] our built-in- game development language, GDScript" could definitely include documentation.

There are at least a few different potential aspects to documentation improvement that I can see:

• Give all the existing documentation a "once over" to:

  • Fix pre-existing language-related issues--perhaps more "editor" than writer.

  • Improve & expand existing explanations.

• Build a solid base to enable longer term ongoing improvements by, e.g.:

  • Evalulate/develop/improve tools[0] and/or processes to:

    • make documentation updating easier;

    • encourage new feature merges to also include at least basic documentation (often related PRs/commits/issues have valuable information in them that just needs to be extracted);

    • reach out to a wider community to encourage documentation contributions.

    • conduct "user experience" research with people who are using Godot for the first time to identify & document common obstacles.

    • help people write/evaluate different "levels" of documentation quality to highlight areas that would benefit from improvement. e.g. "basic" -> "complete" -> "with examples".

[0] Personally I do think the .xml-based generated documentation process is a barrier to contributions--for many people even editing .rst/.md docs with a browser preview is challenging enough. It would be nice if the .xml docs had more online tooling to enable more "drive by" contributions without increasing the amount of work associated with merging them.

Disclosure: I have written documentation "professionally" but I don't particularly like writing documentation and so I'm often thinking of how to get better documentation with less effort. :D

Edit: Incidentally, as an example of something done well, I think the "Docs writing guidelines" is a really helpful document to direct people towards.

[Calinou]

It would be nice if the .xml docs had more online tooling to enable more "drive by" contributions without increasing the amount of work associated with merging them.

I think writing a dedicated tool to edit the XML documenation would be a lot of work for little benefit. Making contributions easier is all about "cost versus benefit". You generally don't want to spend more time trying to onboard others than you could have spent improving the project yourself :slightly_smiling_face:

encourage new feature merges to also include at least basic documentation (often related PRs/commits/issues have valuable information in them that just needs to be extracted);

We'll soon make this a requirement for new pull requests that add exposed properties/methods.

reach out to a wider community to encourage documentation contributions.

Last month, I had the idea of making a class reference contest where the most active contributors earned some money from a prize pool. While it would likely incentivize contributions a lot, there are two pitfalls I can see:

• Measuring the most active contributors will be difficult. We could use something like the number of lines/words modified and exclude spam/vandalism from counting, but anything can be gamed.
• Legal reasons can also make this difficult to organize.

[Feniks-Gaming]

Last month, I had the idea of making a class reference contest where the most active contributors earned some money from a prize pool. While it would likely incentivize contributions a lot, there are two pitfalls I can see:

You could draw a random person from any contributors of that month. This would encourage people to contribute even if it's small change rather than think they can't compete with github behemoths that would be nice way to get new people to get involved.

[golddotasksquestions]

You generally don't want to spend more time trying to onboard others than you could have spent improving the project yourself

Sometimes you do. This is how infrastructure investment works: Forfeit some short term benefit in favor of a greater long term benefit.

[Galaxy613]

To me, as a fledgling Godot user, the most important type of documentation is code examples.

A three-line code example is worth far more than even a paragraph of explanation. It's how I taught myself Blitz3D/BlitzMax when I was younger. And I think it's the primary thing missing from Godot's documentation, code examples seems to mostly be sequestered inside specific tutorials instead of generic documentation.

[clayjohn]

This has been discussed among the core devs for awhile. The consensus is that we would like to hire a professional technical writer to complete and improve the docs.

That being said, it is difficult to find someone with the necessary knowledge and skills. At this point it is a matter of finding a person to do it more than it is whether or not it will be done.

[Feniks-Gaming]

@clayjohn what effort has been made so far in finding such a person. I have seen no "We are recruiting" announcements anywhere. I think getting announcement and clear criteria of what we are looking from a person in this position could help significantly. Having idea of what budget you have to spend on it and job description etc. All the things that any other company would do while recruiting. There are people who do technical writing for a living. They don't need to Godot experts as long as they are good at writing documentation and can work with others to understand the engine.

At this point technical writing skills > Godot skills.

[clayjohn]

At this point technical writing skills > Godot skills.

I have to respectfully disagree here. :) Many of the docs are incomplete because very few people understand them. No amount of writing skills will help a person understand what ProxyTexture or StreamPeerBuffer do. We absolutely need a person who can document such classes _and_ do it in a way that users can understand.

Of course, in the future, hiring someone to solely polish descriptions and tutorials would be nice. But it is definitely a prior to finish documenting everything and replace all instances of:

method x()
description: "x" is used to call method which does x.

[follower]

I think writing a dedicated tool to edit the XML documentation would be a lot of work for little benefit.

I admit that I'm curious about whether the motivations for having the documentation in XML (I assume at least partly for easy link generation & in-engine use) are still as strong as they were originally. Especially given that there's now more potential documentation contributors who won't necessarily be as open/able to going through all the steps required to write, test & submit a documentation patch for the XML-based documentation. (Because they're not actually building the engine from source on a regular basis.)

My impression is that currently there's many fewer steps required to, say, edit a source code comment or text string than there are to edit the XML-based documentation--which seems a bit backwards to me.

I think that being able to edit the XML-based docs online (with preview) as, say, .rst in https://github.com/godotengine/godot-docs/tree/master/classes and have, say, a script that round-trips the changes back to XML would result in more people able to contribute. (Ignoring all the complications involved with making such a tool. :) )

[follower]

We'll soon make this a requirement for new pull requests that add exposed properties/methods.

That sounds positive.

Will the core developers have the support that they need to make this happen? Given the small number of core developers, current code writing demands and amount of time it takes to write comprehensible, understandable & detailed documentation it seems like this change will have a big impact on their time without, say, adding people who can have a 5 minute conversation with the devs on what the new functionality is & how it works and then turn that into documentation.

(Which also suggests tying in an example code/tests requirement might be helpful.)

Related suggestion: Documentation templates

Based on my previous experience with trying to make it easier for developers (including myself :D ) to write useful documentation, I've found having a "documentation template" helpful. Not in the sense of stuff that can be auto-generated (parameters, return values) but in terms of something like:

• What benefit/functionality does this new feature/property/method enable?
• What is a minimal code example of the new thing in use?
• What is the most likely change someone would want to make to this example?
• What traps/non-obviousness do I need to watch out for?
• How is this different to existing similar features?

Not necessarily that particular list, but a series of prompts which a dev can write a, say, one sentence response to each and then ask themselves "Have I answered this question? Great, now I'll move onto the next. Am I done? Yes! Now I can get back to the code.".

And, a series of answers that answer the questions someone who is using Godot is most likely to want answered: e.g. "Does this feature do what I'm looking for?", "How do I change this example to do X?", "Why isn't my code using this feature working?".

As a potentially useful concrete example (based on a recent experience), consider how these questions could be answered for, say, TouchScreenButton.

[clayjohn]

@follower Sounds like a good addition to the Docs writing guidelines

[Calinou]

@follower The rST markup format has limitations a custom XML-based format doesn't :slightly_smiling_face:

One of them is being unable to use any kind of markup inside bold text, for instance.

[willnationsdev]

@Calinou Would it be possible for any created code samples in XML docs to include syntax highlighting and/or language splitting like the RST docs support? Right now, the only thing I think you can do is [codeblock] tags to wrap code samples which doesn't grant either of those features. Perhaps that should be its own Issue.

[Calinou]

@willnationsdev That can be handled on the editor help side, though that means we'd need to add a new tag for GDScript code blocks to distinguish them from plain text codeblocks.

Another question is how to avoid duplicating code with the GDScript syntax highlighter that's already present in TextEdit.

[willnationsdev]

@Calinou Is it really in TextEdit? Shouldn't that be something that the ScriptLanguage implementation handles, so that the language can instruct the TextEdit in how to properly display its language content?

[git2013vb]

To improve the current documentation is easy and anyone can do that - especially the developers.
People need to follow common guidelines for start (for English version):
Do:
Set three sections: beginner - intermediate - advanced.
Define who is the target for each session (beginner/intermediate/advanced)
Speak from game engine point of view all the time.
Add syntax, uses case and possible solutions - one or more. All of these in GDScript, C# and all API.
Be simple clear and complete like talking to a baby/e. (especially in the beginner section)
Describe facts
Link complex words to paragraph where is the explanation

Don't:
Describe personal point of view.
Add words like (maybe, in some cases, not often, many, few, explain how to, appropriate, several, must, don't, necessary, unnecessary, likely.. etc) - adjectives . So anything that describe something not as defined as fact that will be easy to count.
Add your opinion about anything
Add question marks

[Calinou]

@NathanLovato has been hired part-time to work on the Godot documentation (see https://github.com/godotengine/godot-docs/issues/3969). We can close this now :slightly_smiling_face:

[NathanLovato]

I think that the proposal included and maybe was more about the built-in class reference than the online reference manual. The reference manual (pages covering the editor, available features, and general topics like networking, optimization, etc.) is actually at a lower completion rate than the class reference right now, and still less than 95% complete. Probably less than 80% complete, actually, which is in part why I got hired to work on it instead of the class reference for this first mission.

All in all, I'm unsure this addresses the proposal. The OP may want to confirm this.

[reduz]

Working much on class reference right now does not make much sense with core apis being changed for 4.0. Will probably make more sense after 4.0 is stable to put effort on that.

[NathanLovato]

Definitely.

We should also point out that the class reference is getting PRs almost daily. It improves progressively so improvements can be hard to spot, but if users open issues regarding classes that are really bad, as long as it's not too big a job, contributors will jump on it and often PR within 24 hours. I've reviewed dozens of improved docstrings over the past few days and all PRs got merged.