RFC: [Learning team] - Remove as much friction from the doc contribution process as possible

[havremunken]

As a hobby developer and occasional user of RxUI (I love it!), I consider myself very new to this side of the project, i.e. actually contributing to it. I am now a member of the learning team, but I am as of this writing completely, 100% ignorant of how the process of contributing to the docs happens. That is why I am writing this RFC now - so that hopefully, I can make some relatively unbiased comments on stuff that would be nice to have to lower the barrier to contributing good docs.

As we all probably know, writing docs is not usually what OSS developers want to spend their time on. There is usually little intrinsic motivation in that until the project reaches a certain size and popularity. RxUI seems to be at a point where material that would help people understand the benefits of using the project needs a level-up. And it isn't just potential users we could be missing out on. Potential new project contributors are out there, but without helping them understand how to help RxUI, perhaps they'll spend their energy elsewhere.

Of course, there is Kent Boogaard's book (and in time, Geoffrey Huntley's course). I'm not advocating competing with it. In fact, I think the docs should recommend buying and reading it, with references to specific chapters, for a fuller understanding of RxUI. But we need to get people started first. If using RxUI depends on ordering and reading a physical book, many will choose a path of less resistance. We need to make them see the elegance of RxUI and WANT to use it and WANT to buy the book. :)

The point of this RFC then is to figure out what we can do to make it as easy as possible to contribute documentation, to update documentation with short iteration cycles, to create complete and awesome docs that are ready at the same moment a new feature is released. You get the point.

As an example, I don't know how documentation is written today, as in - the format. Html? Markdown? LaTeX? DocX?

Would it not be good if as much as possible of the documentation could be done via a simple-to-learn format such as markdown, and then figure out a way to link pages together on the web site?

Structure is needed, no doubt. But within a well defined structural constraint we could hopefully thrive and produce good learning material.

Another point; We're going to write docs for a project that helps programmers write awesome user interfaces. What do we need besides text? Two things that we're going to need are screenshots and source code listings. So let us make those easy to get right by default. There is probably some form of code formatting style online somewhere we can borrow to make our code examples look awesome. And we'll come up with some rules for screenshots to make our docs look like they were done on purpose and not like they just kinda happened. And we'll need some spell checking for the non-native english speakers among us like myself. Correcting language - both syntax, grammar, but also rewriting sentences to make it easier to understand - should be welcome.

Then there is the matter of the different platforms RxUI supports. I work primarily in WPF. I have an iPhone myself, but I never programmed for it, and my experience with Android is completely non-existent. How do we make sure a UWP user or an Xamarin Forms user feels welcome when they read the docs? Should we have a "Platform" dropdown in the upper left corner, and then some sort of modular structure to the docs, showing the parts relevant to what they're after?

In the same way that we have different platforms, we also have different languages. I understand we already have several multilingual people on the team. I'm norwegian myself and there are only about 5 million of us (and not all of us are RxUI users, believe it or not) and most of us read english fairly well, so that language isn't very relevant anyway. Of course, huge world languages such as spanish needs to be addressed. And there are users in countries like Germany and France that would prefer their own language if possible. On this subject, our primary constraint is people. As long as we don't have someone with the capability to write solid German, there is little we can do. But once we acquire that person (or preferrably, more of them), how do we get them going with a mountain of docs?

Documentation is a huge subject that could probably justify way more than a single RFC. But for the learning team to agree upon how to do their job would be a great start. :)

[lythix]

Love that Wyam supports examples in the comments. Thanks for pointing that out, I've not used it before but it sounds awesome.