Documentation Strategy

#1

Hi all,

First off I would like to say that I really appreciate all that Silicon Studio, and it’s developers, has done with this engine. Nothing here is a criticism, instead it is a discussion about the (hopefully near) future of Paradox. Also, what is said here will be obvious to everyone I am sure, but I wanted to get it out here. This is directed at the Paradox devs, but it is also a discussion for the whole community as we will I think have a part to play.

Right now the biggest barrier to entry for Paradox is, in my opinion, a lack of documentation. I have ported my own WIP game from Unity, and much of my time has been spent going through the examples (which are nice, but sparse) and combing through the source code on Github, trying to figure out how to do relatively simple tasks. This is not a complaint, I knew what I was getting into.

Many, if not most, people will not have the experience necessary to learn the engine as I have. I really want Paradox to be successful, because that will benefit everyone. But to become successful it needs to be far more accessible.

For true accessibility the studio needs to become more full-featured and user-friendly, but I believe an important step for Paradox at this stage is to make it more accessible to coders/programmers/developers. To do that we need much better documentation of the API, with fleshed out descriptions and code samples. Tutorials are important too, but I believe they are secondary to the base documentation.

I would like to know what your strategy is for documenting Paradox, and what the community (including myself of course) can do to help?

Thanks,

Mark

1 Like
#2

Hi Mark,
Thanks for your feedback! We are definitely looking to improve the documentation in the coming months. Many parts of the engine has changed in the recent release, and due to resource constraints, we didn’t have time to release documentation updates as part of the latest version. We will try to upgrade it in the coming weeks.

Concerning the strategy, we have to balance priorities between having part of the engine code enough stabilized, so that the we are confident the API won’t change, and update the documentation once it is fairly stable. For example, we did document how Materials were handled in Paradox in the first version, but the underlying API was far from our target, so we didn’t invest improving it. As we are a bit more settled on this side, we will be able to update the documentation accordingly. Our goal is to stabilize a large part of the API by the end of this year as we have still lots of challenges ahead (like an efficient D3D12/Vulkan rendering path) that could require some major refactor (and breaking changes).

About the help from the community, leave a post in this forum whenever you struggle to do something with the API. The more we have precise feedback on things that are not easy to use and/or understand, the more we can target our effort more efficiently at fixing the API and/or documentation!

#3

Will the documentation itself be on Github?
That way we could provide pull requests etc.

#4

That’s a good idea… though, our documentation is partially written in confluence… so this might be a bit more difficult to expose it externally. We will have to check if we have some way to improve this.

1 Like