Improving the FAQ

Anything related to PR, release planning and any other non-technical idea how to move the project forward should be discussed here.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Improving the FAQ

Post by Ravenwing »

Thunderforge wrote: 12 Aug 2018, 04:09 Alright, I went ahead and went hog wild and made a bunch of changes to the FAQ draft. I added a few key questions from this list and wrote several answers myself (there were a few other questions there that I thought were less pressing, so I didn't include them). I also removed the FAQ video because it was extremely old and did not provide a good reflection of the current state of the project.

Let me know what you think and what further changes should be made.
This is really great Thunderforge! I think you've abbreviated and split up information nicely. And I think the aforementioned discussed changes are good as well.

I agree we probably don't need every single one of those questions from the "master" list. I do think some more probably need to be added, but I need to look at them with fresh eyes again this week. This doesn't need to be added in this iteration, but I do insist on adding the question about what a game engine is. I think 70% of the "dumb" questions we get are because people don't really understand what that means. It's not immediately obvious or intuitive for someone who's never really thought about how games are made before. As long as you don't mind making some additions and modifications in the near future though, I'd say this is ready to publish. (although the first question is still justified, so maybe fix that first)
psi29a wrote: 13 Aug 2018, 16:18 also... let's try to be consistent since on GitHub, GitLab and other places it reads:
OpenMW is an open-source open-world RPG game engine that supports playing Morrowind.
With the emphasis on the fact that it is a game engine in it's own right and not made to just run Morrowind.
This has been annoying me as well. I've been trying to write a version that is both simpler and more comprehensive, and it's causing me difficulties. I'll have a version we can discuss with the other questions I want to add.
Pookie
Posts: 3
Joined: 19 Aug 2018, 13:39

Re: Improving the FAQ

Post by Pookie »

Hi Chaps,

I came across OpenMW about a week ago, and have been playing it in preference to vanilla Morrowind ever since.
I have also been reading here extensively, as I would hope to be able to contribute to the effort in the future (I am a certified techie).

I hope that you will find the views of a newcomer helpful - particularly regarding the FAQ, for whom newcomers are a prime target audience.

I read the current FAQ upon my first visit to this site, and was baffled by it. I have re-read it today, and would cite 3 major issues with it:
1. It has a great deal of technical jargon / acronyms only some of which are explained or hyperlinked (e.g. non-blocking, ESM, ESP, BSA);
2. The structure is unbalanced, with a very long answer to the first question, then pithy answers thereafter;
3. It answers few of the basic questions that I did have, but several esoteric questions that I didn't have.

I also read the draft FAQ today, and found it to be instantly comprehensible, immeasurably better, and largely addresses the issues that I cite above.

I have a couple of minor suggestions for further improvement:
1. Add the question/answer: What Languages (e.g. French, Russian, Polish) does OpenMW support ?
2. Add the question/answer: When do you expect to release OpenMW v1.0 ?
3. Add a Glossary (possibly held in the wiki). I think that this would prove particularly helpful for newcomers who wish to contribute to the project, as Forum technical threads, Bug Reports etc. are understandably and necessarily jargon-laden (e.g. fork, PR).

I hope that you find these ideas helpful.
Best Wishes, John (aka Pookie).
User avatar
lysol
Posts: 1513
Joined: 26 Mar 2013, 01:48
Location: Sweden

Re: Improving the FAQ

Post by lysol »

Thanks for popping in! Well thought out points. The three questions you suggest would be good to have in the FAQ.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Improving the FAQ

Post by Ravenwing »

Pookie wrote: 19 Aug 2018, 14:45 I hope that you will find the views of a newcomer helpful - particularly regarding the FAQ, for whom newcomers are a prime target audience.
Yes! We appreciate the constructive criticism and it makes me glad we decided to revisit this content. I think part of the problem that you've noticed is that we're a fairly technical group and, until relatively recently, have attracted a mostly technical crowd. I'm glad we're moving in the right direction though, and I like all three of your suggestions. We have a very lengthy list of potential questions some of our members have thought up, and I don't think we had a supported languages question on there, so I'll add that to it. In case you're still wondering:

1) Someone please correct me if I'm wrong but, we support playing Morrowind itself in whatever language you own the game in. The OpenMW specific interfaces like the launcher and OpenMW-CS and any in-game additions should be supported once we provide localization support post-1.0. This will of course depend on people translating the content for us. We won't support translating the game into languages other than what you own, as that all depends on content files, which we cannot provide for legal reasons.

2) We'll definitely have this in the FAQs, but it won't be an answer anyone likes lol. We've been burned in the past by giving estimates and having people misconstrue comments by developers, so we aren't going to give a time estimate. Since we're entirely powered by the efforts of volunteers working in their free time, a conservative projection today might be an absurdly obtuse projection tomorrow. Right now we're "close", for OpenMW, but "very far off" for OpenMW-CS. Most of the post-1.0 features we'd like to implement soon after release require a fully functioning editor, so there's really no reason to release one without the other. Or at least I believe that's the current general sense I've gotten around here. I'll probably insert something in there about how if we're not in a release-candidate phase for 1.0 then don't believe anything anyone says.

3) I really like this idea. I'll add it to my list of planned PR content. And yes, the wiki is probably the most appropriate place for it. FAQs are especially hard for this kind of stuff, because you can't just explain the term at the top like you would in something you're supposed to read from top to bottom. In those kinds of documents you can assume people now know where to at least look to remind themselves of what it means. In an FAQ, especially with a table of contents, this would be a very poor assumption.

If you have any more suggestions in the future, please let us know!
User avatar
Thunderforge
Posts: 503
Joined: 06 Jun 2017, 05:57

Re: Improving the FAQ

Post by Thunderforge »

Alright, I'm currently at what I think is the "final draft" of the FAQ (although it's by no means the final version, as I hope we make many changes in the future). The biggest change is that the question about no visuals and the stuff about pink textures due to S3TC stuff have been removed because this Merge Request adds it to our Common Problems documentation. Having all of the troubleshooting problems in one place seems like a better option.

If we are happy with this, then I'll update the table of contents and publish it. I'm of course open to further changes later on.
Ravenwing wrote: 14 Aug 2018, 05:50
psi29a wrote: 13 Aug 2018, 16:18 also... let's try to be consistent since on GitHub, GitLab and other places it reads:
OpenMW is an open-source open-world RPG game engine that supports playing Morrowind.
With the emphasis on the fact that it is a game engine in it's own right and not made to just run Morrowind.
This has been annoying me as well. I've been trying to write a version that is both simpler and more comprehensive, and it's causing me difficulties. I'll have a version we can discuss with the other questions I want to add.
I agree, we should be consistent. I'm fine with changing the FAQ further once we decide what we want our consistent version to say.
Pookie wrote: 19 Aug 2018, 14:45 also read the draft FAQ today, and found it to be instantly comprehensible, immeasurably better, and largely addresses the issues that I cite above.
Yay! Glad to hear that we're succeeding in our goal!
Pookie wrote: 19 Aug 2018, 14:45 I have a couple of minor suggestions for further improvement:
1. Add the question/answer: What Languages (e.g. French, Russian, Polish) does OpenMW support ?
2. Add the question/answer: When do you expect to release OpenMW v1.0 ?
3. Add a Glossary (possibly held in the wiki). I think that this would prove particularly helpful for newcomers who wish to contribute to the project, as Forum technical threads, Bug Reports etc. are understandably and necessarily jargon-laden (e.g. fork, PR).
I agree, these should probably be added. Anybody want to draft up answers to them?
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Improving the FAQ

Post by Ravenwing »

I looked at Atahualpa's old video transcripts to see if we'd answered this:
Q:
OpenMW seems to be rather complete. When do you expect version 1.0 to arrive? X

A:
OpenMW is an open source project, and every team member working on OpenMW does so on a voluntary basis. That said, we don't give exact release dates. But let me give an estimation instead: I would say that we will have two to three minor releases until version 1.0 is ready, i.e., 0.41, 0.42, maybe a 0.43 and, then, an OpenMW 1.0.0. Given an average time of three to four months per release and counting from September 2016, we end up with a 1.0 release between June 2017 and January 2018.
Wah wah, guess not!

Here's a slightly modified version of my answer above:
Short answer: ¯\_(ツ)_/¯
Longer answer: We've been burned in the past by giving estimates and having people misconstrue comments by developers, so we aren't going to give a time estimate. Since we're entirely powered by the efforts of volunteers working in their free time, a conservative projection today might be an absurdly obtuse projection tomorrow. Right now we're "close", for OpenMW, but "very far off" for OpenMW-CS. Most of the post-1.0 features we'd like to implement soon after release require a fully functioning editor, so there's really no reason to release one without the other. If you have experience with C++, we could always use an extra hand (or two) to help us reach this important milestone faster! See the <link to developer checklist> to get started!
Is that too informal? Doesn't get to the point clearly enough?

And if my answer to the languages question is all correct, feel free to use that as a placeholder.

I'll include answers to both of these in my list at some point, but don't wait for that. I haven't had much free time to work on it.
As for the glossary, that would be a great task for a newbie who wants to help contribute to the project, but who doesn't have enough programming experience. I'm willing to do it, but that means it gets added onto my pile of things that aren't getting done lol
User avatar
Thunderforge
Posts: 503
Joined: 06 Jun 2017, 05:57

Re: Improving the FAQ

Post by Thunderforge »

The site FAQ has now been updated to the draft version. Thanks to everyone who provided suggestions!
Ravenwing wrote: 21 Aug 2018, 06:13
Question: OpenMW seems to be rather complete. When do you expect version 1.0 to arrive?
Short answer: ¯\_(ツ)_/¯
Longer answer: We've been burned in the past by giving estimates and having people misconstrue comments by developers, so we aren't going to give a time estimate. Since we're entirely powered by the efforts of volunteers working in their free time, a conservative projection today might be an absurdly obtuse projection tomorrow. Right now we're "close", for OpenMW, but "very far off" for OpenMW-CS. Most of the post-1.0 features we'd like to implement soon after release require a fully functioning editor, so there's really no reason to release one without the other. If you have experience with C++, we could always use an extra hand (or two) to help us reach this important milestone faster! See the <link to developer checklist> to get started!
Is that too informal? Doesn't get to the point clearly enough?

And if my answer to the languages question is all correct, feel free to use that as a placeholder.

I'll include answers to both of these in my list at some point, but don't wait for that. I haven't had much free time to work on it.
As for the glossary, that would be a great task for a newbie who wants to help contribute to the project, but who doesn't have enough programming experience. I'm willing to do it, but that means it gets added onto my pile of things that aren't getting done lol
I was hoping to have someone else comment on this, but I agree that it is a needed question. I like that your version includes a call to action, although we should also keep it open to testers and other roles as well. Let's see if anybody has a better suggestion, and I might write a version too at some point.
User avatar
Thunderforge
Posts: 503
Joined: 06 Jun 2017, 05:57

Re: Improving the FAQ

Post by Thunderforge »

Okay, I've reviewed this text privately with some of the core contributors and we're all pretty much okay with this:
When will OpenMW and OpenMW-CS reach version 1.0? (This will be immediately after this question discussing why we are not yet on 1.0)

There are still a number of issues that need to be addressed before we believe that we have reached parity with the original Morrowind game engine and construction set. In particular, many of the new features we are planning for post-1.0 will require a functioning editor to make use of in mods, so bring OpenMW-CS to parity is very important.

The best way to make sure that OpenMW and OpenMW-CS reach version 1.0 faster is to help! Please check out how to help the project. We can always use help writing code, testing, or generally just providing feedback.
I think that this is an improvement on the one from Ravenwing (which I liked due to its call to action) because it's a bit less colloquial, it sets a clear goal, and it note sthat help can also come from non-coders.

What do you all think? If people are generally okay with it, I'll add it to the FAQ.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Improving the FAQ

Post by Ravenwing »

I like it. Should Construction Set be capitalized and italicized as name of that piece of software? Also, last sentence first paragraph, should be “bringing”. But yes, this matches our style much better :)
User avatar
Thunderforge
Posts: 503
Joined: 06 Jun 2017, 05:57

Re: Improving the FAQ

Post by Thunderforge »

Ravenwing wrote: 28 Aug 2018, 01:29 I like it. Should Construction Set be capitalized and italicized as name of that piece of software? Also, last sentence first paragraph, should be “bringing”. But yes, this matches our style much better :)
I agree, Construction Set should be capitalized. I wasn't sure whether or not we should italicize it, and the Wikipedia article on Morrowind is inconsistent on that front. I went ahead and decided to capitalize it. I've also fixed the typo.

I think that's everything for now on the FAQ! Thank you to everyone who provided feedback. If you have additional changes to make, please write below, create a new topic, or PM me directly as appropriate.
Post Reply