[COMMUNITY] "Lack of docs" whining has been a hot topic for years. Is there a viable solution? I think so.

[VictorBurgos]

First off, I am going to start off with saying, that YES, I know we can just go to source and find pretty much anything we want, 95% of the time it's decently commented. On the flip side, most new devs or even veterans that are using Blueprints don't have Visual Studio installed. Meh, that's fine. We have API docs, but they aren't that great. We do have github though! But, let's say some devs don't have access, don't want it, or just have no clue how to get it.

Epic leans on the community quite a bit for a lot of things, especially fixing broken code or exposing things to Blueprints via plugins. (I am writing specifically for BP because most C++ devs can just look at source at will).

So why aren't you leaning on us for your official documentation?! Let us crowdsource this thing! Yes, we have the wiki, but that's not what I am getting at. So, with crowdsourcing, anyone OR a selected few in the community would be able to write drafts for official documentation on practically anything. It would go through a review through the Doc Team which will then, after possible revision requests or edits themselves, be posted while crediting the author(s).

An addition to this, I propose a "Needs Update!" button found on each page. If any dev finds a mistake in the documentation, it will get flagged in some queue that either the official doc team or the community doc team can look at.

Let us help you help us.

[mittense]

I think there's a wiki that already exists and the documentation search functionality checks that, forums, and the official documentation. I, personally, want the official documentation to be written the definitive authorities on the code/engine/functionality/etc., even if it's not necessarily up-to-date.

That said, I do think that it would be delightful to highlight an area of the documentation that is especially in need of updates.

[WolfyJowol]

For starters I would like to say this is a glorious suggestion. With UE4 evolving at such a rapid pace and relying on the community, the Doc Team would be able to focus on submitting proper guides as opposed to finding out what is needed, what isn't, what needs to be corrected and so forth. Ontop of that, the UE4 community is not only one of the most active communities, but helpful ones as well. The fact we now have community led training proves this point. Going back to the pace UE4 evolves at, I think the "Needs Update" button should almost be mandatory for each page that is created. If anything, I think it would be interesting to see if Epic starts with the Needs Update button, then wait a month or two to gauge how much actually needs to be modified. (I am sure they're are keeping track of what needs to be updated to some extent, but this way we can think of the community as QA Testers of sorts.) If it becomes too overwhelming, then the implementation of the community outsource could become a viable option.

[EntrpriseCustomr]

Or a Dev Grant for a more complete BP-Node resource would be a big help.
The BP docs right now are a single line of detail, params, and a screenshot etc.

Just some examples, but take the likes of this from Romero or this from eXi etc.
But go beyond that, and explain the assumptions / catches, in using every node.

Just some quick examples of where some extra detail is badly needed: 1 2 3...

[cyaoeu]

I agree, mainly because there are things that are just wrong, like this: https://docs.unrealengine.com/latest...ference/Color/ , which says that 0 = fully desaturated and 1 = original color, when it's really the other way around.

[Jeff Wilson]

We have been wanting to enable the community to help us on the documentation for quite a while. The wiki is a good outlet, but it doesn't help to have up to date info on the wiki contradicted by outdated info in the documentation. Unfortunately, we had neither the infrastructure to build the pipeline nor the resources to deal with the influx of submissions.

The good news is we are getting close to having the infrastructure we need to be able to make a sustainable pipeline. I don't know exactly what that pipeline will look like yet, but at the very least it would enable you to send us feedback. Ideally, we want to be able to empower community members to update content directly and have that go through a review process to ensure the quality of the content we publish. That's where resources on our side come into contention. I think we can do it, though.

I don't have a timeline to share of when all this will start to trickle out, but we will share our plans as they are ready for a wider audience.

[EntrpriseCustomr]

The good news is we are getting close to having the infrastructure we need to be able to make a sustainable pipeline. I don't know exactly what that pipeline will look like yet, but at the very least it would enable you to send us feedback. Ideally, we want to be able to empower community members to update content directly and have that go through a review process to ensure the quality of the content we publish. That's where resources on our side come into contention. I think we can do it, though. I don't have a timeline to share of when all this will start to trickle out, but we will share our plans as they are ready for a wider audience.

Sorry to call you out Jeff, but you should re-read your own Posts from threads from two years ago.

For example: Here & Here ... What's really changed since then???

Even if you open a platform to the Community soon, it will take a long time to build up quality Docs...
Then there's the whole issue of Editing / Stylizing it, so its consistent with all other existing Docs etc.

Epic are a genius game-engine company of the highest caliber, but the engine is still changing a lot...
In this scenario its hard to get Docs right too. So wouldn't a Dev-Grant for this make more sense?
Docs shouldn't require a new platform, even detailed PDFs done by the right team could help hugely!

I just wish Epic overall would stop Auto-Generating docs and pretending its Documentation, as its not!
Victor's advice here about leaning on Source even for BP is maybe the most practical in the meantime...

[VictorBurgos]

We have been wanting to enable the community to help us on the documentation for quite a while. The wiki is a good outlet, but it doesn't help to have up to date info on the wiki contradicted by outdated info in the documentation. Unfortunately, we had neither the infrastructure to build the pipeline nor the resources to deal with the influx of submissions.

The good news is we are getting close to having the infrastructure we need to be able to make a sustainable pipeline. I don't know exactly what that pipeline will look like yet, but at the very least it would enable you to send us feedback. Ideally, we want to be able to empower community members to update content directly and have that go through a review process to ensure the quality of the content we publish. That's where resources on our side come into contention. I think we can do it, though.

I don't have a timeline to share of when all this will start to trickle out, but we will share our plans as they are ready for a wider audience.

Sounds good. But I would like to point out that the Wikis are just as bad at being kept up to date. Or just don't have the necessary information that users are looking for. As for this future pipeline that's incoming, I would have assumed, you as the Docs lead, would be the first to know about things in those regards or at the very least had a hand in the development.

But yeah, looks like the pipeline is very similar to what I was going on about anyway. Hopefully we'll see something 1H 2018.

Thanks for the response.

[EntrpriseCustomr]

I would have assumed, you as the Docs lead, would be the first to know about things in those regards or at the very least had a hand in the development.

Yep, lots of maybe's in there, like POTUS election promises... But hey fingers crossed!

[mittense]

Sounds good. But I would like to point out that the Wikis are just as bad at being kept up to date. Or just don't have the necessary information that users are looking for. As for this future pipeline that's incoming, I would have assumed, you as the Docs lead, would be the first to know about things in those regards or at the very least had a hand in the development.

I'm not entirely sure what you're getting at here anymore. You want the documentation to be updated more frequently and with more information — "crowdsourced" was your word. That would, basically, mean establishing some sort of wiki (maybe with a hierarchy of privileges).

But then you also say the wiki is just as bad about being updated.

Soooo, uh. You want the same concept except that same concept to work?

Granted, there are reasons why the existing wiki isn't great at being updated — it's got a real awkward navigation/interface setup. But you're still going to be dealing with a limited population of people who are updating documentation — it's not like Wikipedia where the entire world is involved.

[VictorBurgos]

I'm not entirely sure what you're getting at here anymore. You want the documentation to be updated more frequently and with more information — "crowdsourced" was your word. That would, basically, mean establishing some sort of wiki (maybe with a hierarchy of privileges).

But then you also say the wiki is just as bad about being updated.

Soooo, uh. You want the same concept except that same concept to work?

Granted, there are reasons why the existing wiki isn't great at being updated — it's got a real awkward navigation/interface setup. But you're still going to be dealing with a limited population of people who are updating documentation — it's not like Wikipedia where the entire world is involved.

They are two different things entirely. I'm not sure if you just didn't read it all, or just missed something, but it's explained pretty well what I am looking for and was thinking. Jeff got it, and it seems like they are on track to something similar to what I was envisioning anyway. Hopefully. We'll see soon enough.

If you want to continue using "wiki" (even though this has nothing to do with them), then you can think of them as "Curated Wiki entries" of sorts. But even that isn't what I'm going for (something a step above). It's just a way to fill in the voids that the documentation team is obviously having issues with by having the community submit entries to the Official Doc team to be published. The "control" never leaves the Official Doc team.

Maybe this will be better analogy: We can think of the Doc Team as Editors/Publishers and the Community Members who submit as Authors.

My reasoning in all this, is they must already have something similar setup up to that, because there's no way the Doc Team members are also SMEs in each published articles. SMEs= Subject Matter Experts. But who knows, maybe they do have one member from each respective branch of the engine hammering away. Or, one's just chosen as an extra job on top of their regular duties. /shrug. No idea.

[thadkinsjr]

I went to mobile since 4.17 released to spend a week prototyping something simple. Thinking that ES2 being excluded would be better. It's not. Some textures show up. Some don't. Some pixelate, and some don't. Some panners glitch, and some don't. Shame really. I see some beautiful games published with UE4 on, Android, and IOS, but I fail to see documentation on examples other than Icelands, and firelands. Mobile development using 3d is like a bad habit, and I keep going back to it see if it's better. Everytime I build to device I think my Ipad becomes an old Atari. It can turn 1024 beauty into an 8 bit monster.

[Jeff Wilson]

Hey franktech,

Sorry to call you out Jeff, but you should re-read your own Posts from threads from two years ago.

For example: Here & Here ... What's really changed since then???

I'm glad to see people actually read my posts. Those posts reflected our plans and goals at the time, but sometimes plans change or get put off due to other circumstances. Our goals never changed though. That's the risk we take when sharing our plans, but I would rather let you know what we want to do than just keep everyone in the dark.

Don't hesitate to call me out on this stuff if you don't see progress.

Even if you open a platform to the Community soon, it will take a long time to build up quality Docs...
Then there's the whole issue of Editing / Stylizing it, so its consistent with all other existing Docs etc.

Yep, it takes time to generate good content, and it takes resources to review and maintain it as well. Like I said, that's going to be the tricky part.

Epic are a genius game-engine company of the highest caliber, but the engine is still changing a lot...
In this scenario its hard to get Docs right too. So wouldn't a Dev-Grant for this make more sense?
Docs shouldn't require a new platform, even detailed PDFs done by the right team could help hugely!

What we want to do is build a sustainable pipeline for community contributions. We could do one-off contributions with the platform we have today, but we need better tech to enable it on a wider scale which would provide the most value to everyone. That doesn't mean we aren't open to and actively seeking community contributions currently. It's just that our vision is bigger than that.

I just wish Epic overall would stop Auto-Generating docs and pretending its Documentation, as its not!
Victor's advice here about leaning on Source even for BP is maybe the most practical in the meantime...

We are also actively working on addressing this as well. Our current goal for this is to add descriptions and explanations written by our team with input from the engineers and drastically increase the amount of example code included in the API reference. Due to the size of the code base, there is a large surface area to cover here so it will take time. We'll begin by hitting the most common classes, functions, etc. and work our way out from there.

[EntrpriseCustomr]

We are also actively working on addressing this as well. Our current goal for this is to add descriptions and explanations written by our team with input from the engineers and drastically increase the amount of example code included in the API reference. Due to the size of the code base, there is a large surface area to cover here so it will take time. We'll begin by hitting the most common classes, functions, etc. and work our way out from there.

Cheers for listening Jeff Wilson!

Sounds great! Examples in particular but also any caveats that apply esp. Multiplayer.
What makes BP successful is having confidence in it, that its robust & won't break etc.
That's why its critical to not write 'This should be used cautiously' but omit the reason...
Or have nodes that appear the same but no docs to confirm it or say if they're different:

Examples:
ConvertScreenLocationToWorldSpace
Deproject Screen to World

BTW: Has anyone thought about adding a Jump-to-Code Right-Click option into BP-Nodes?
If the code comments add value as Victor argues, then why not offer this, 'its for free', no??

[Moth Doctor]

BTW, are you talking about "Go to definition" option? It's there for long time
And it's get some love in 4.18, jumping directly to function in code, not just it's source file.