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.
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.
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.
I agree, mainly because there are things that are just wrong, like this: Color Expressions | Unreal Engine Documentation , which says that 0 = fully desaturated and 1 = original color, when it’s really the other way around.
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.
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. 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.
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.
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.
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.
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.
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.
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.
I have to speak on someone who complained about this all the time. I started off a complete noob knowing nothing, looking at the docs and seeing odd computer science terms told me I had to study Computer Science. In a way they gave me experience to be able to look through a lot of documentation and skill sets. hey i went from a thousand lines of code wow… to meh just a thousand lines of code. But they do forewarn it’s not finished.
Well, yeah… Probably it’s available only if you have VS installed. I have it on every machine.
See attached screenshot.
I understand that in theory it would be nice to have code preview in Blueprints. In practice it could be very cumbersome…
If you preview code, you really want to have syntax highlighting, ability to easily jump between .h and .cpp, inspect related methods, variables. You have it all in IDE and it would be a wasted effort to duplicate some of these features just for preview.
The gold standard in documentation in my opinion is QT. Here’s a link to a class: http://doc.qt.io/qt-5/qactiongroup.html – Go roam there and if UE4 could emulate something like that, game over! How we get there…? Victor’s idea…? Not sure…
Hi. This was 1.5 months ago… Any news on when you can share the improvements? Will there be examples attached to pages (like how QT5 and MS does)? Will the documentation be more than just automated code comments? Can you give us a sneak peek of what is coming down the pipe in terms of documentation improvements? Thanks.
Regarding the infrastructure improvements, in addition to the potential community contribution benefits mentioned previously, these new tools will empower the members of our team to be more productive - this means more documentation can be written. They will enable us to better track the state of our documentation - this means documentation will be more up to date. There is a lot more to this initiative that we think will result in a better information, better coverage, and better experience for everyone, and we plan to share details about it with you very soon.
As far as examples in the C++ API reference, we actually already have these in some instances as you can see here:
These are just a few of the existing examples, but we realize we are far from where we want to be. Improving the C++ API reference is our top priority. We want it filled with useful information. We want it to have meaningful example code. That’s not an easy task and it’s not an overnight fix. We are working on a long-term, sustainable plan to improve and maintain this area of our documentation. We are committed to this and you should hold us to the fire and call us out if you don’t see meaningful changes happening.
The only thing that works in this area is MSDN; but it works because there are millions of contributions by their community every month.
Unity is trying to copy the model, someday they get there, but I fail to see Unreal at that level any time soon.
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.