User Documentation

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

User Documentation

Post by Ravenwing »

Hi everyone! So I've finally started getting our new ReadTheDocs-based user documentation content at a level that is acceptable to read. http://openmw.readthedocs.io/en/master/index.html A HUGE thanks to psi29a for setting up such a handy documentation system!

In discussions with scrawl, we decided it would be inappropriate to duplicate wiki content, but I felt strongly that things like settings.cfg belong in official user docs, so we think it would be best to port the content and delete what's left on the wiki. This has several advantages, the largest of which is documentation that is appropriate for each version of OpenMW. I've already ported the entirety of the Settings section from the wiki and would like it if those with an extra few minutes could look through and make sure I haven't left out anything important before we delete the wiki portion. Atahualpa, I'll wait for your go-ahead since you're kind of the PR manager around here.

Next I intend to port Fonts and Texture Modding before deleting those as well. I don't intend to port Native Mesh Format conversion stuff because it deals specifically with third party software that I don't think we need to officially support. That sort of tutorial is much more suited to the wiki since anyone can edit it more easily and it's more likely to change in ways unrelated to OpenMW version differences. None of this is to say that we're taking control away from anyone. All of the content will be largely duplicated when ported so there will be no loss of content. And this is still completely open source, so if you want to see a change to the documentation submit a pull request on GitHub! The markup, ReST, is actually quite easy to learn, so making changes is easy. Which leads me to...

If you want to help out OpenMW, but can't contribute to bug squashing, in addition to play testing for said bugs, you can help write the user documentation! Just post in Join The Team, and someone will give you more detailed instructions on what to do.

Feedback is constantly welcome! If you think the formatting or wording could be clearer in the documentation, let us know!
User avatar
AnyOldName3
Posts: 2666
Joined: 26 Nov 2015, 03:25

Re: User Documentation

Post by AnyOldName3 »

Well I've already found a wrong thing and submitted a PR to fix it. Good work, though.
User avatar
Atahualpa
Posts: 1176
Joined: 09 Feb 2016, 20:03

Re: User Documentation

Post by Atahualpa »

Thank you very much, Ravenwing! :)

I (quickly) read through the settings documentation and compared it with the former wiki pages. Apart from formatting issues and spelling mistakes (some of them in the original texts), I noticed that the "difficulty" and "show effect duration" settings in the Game Settings section are missing, as well as the "buffer cache max" setting in the Sound Settings section. Is there any reason for this?
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

Perfect, thanks guys. And I believe the reason was something along the lines of I got up from my computer, sat back down, and forgot where I was :lol: There's definitely still plenty of formatting I want to fix, but I wanted to get the initial draft up with the actual content so we could move on from there. I just submitted another PR to add fonts and paths. I probably won't work too much more on this today, but I do want to go through and massage the formatting and actually do a real proofread in the near future.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

I am checking the code (just got some spare time today :P) and I have 2 quick questions:

1. Any recommended tool. I see Ato.io has some plugins.
2. Isn't RTD site synchronized automatically? I saw that fonts is in the index (https://github.com/OpenMW/openmw/blob/m ... /index.rst) but it is not shown in the RTD index. I can search for it though.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

No problems:

1) I use a text-editor, but you can edit the files on github itself if you see small typos. If you use windows, there is a github application.

It is best to have a way to build the docs yourself locally with Sphinx, so you'll need Python installed to do that.
Normally once you have a terminal open, make sure you are openmw/docs/source and then do a make(.bat) html. You can then preview your work via openmw/docs/build

2) RTD is synced on releases, so when all tagged releases have documentation made. It also follows the Stable tag which is set to the latest release. This is the default when you got to RTD. You can select which version of the documentation you want on the left side, near the bottom.

However if you just want to write documentation, I'm sure someone here can take what you've done and convert it to ReST for inclusion. Up to you.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: User Documentation

Post by Ravenwing »

In regards to 1) do you mean any tools for WYSIWYG editing that saves into .rst format?
If so then I'm not aware of any, but I didn't look too hard. You can use this to preview in real time what you're typing. You can also see it on GitHub once you push to your working branch, but this can be a tedious way of previewing and it mucks up your branch history. Psi29a gives the best recommendation, as it will let you preview your inter-document links (what I usually have the most trouble formatting correctly) and is the most rigorous. However, if you don't want to deal with setting that up, the first link is probably your best bet.

If you're having a hard time with ReST, I recommend using both Sphinx's guide and the quick guide on ReST's website as they show you how the different markup will look. Obviously this doesn't replace reading through some of the actual specification, but it's a hell of a lot easier being able to see what it will look like.

Does anyone think it would be beneficial for me to write a tutorial on how to get up and running to contribute to documentation? It doesn't sound like you're having too much difficulty Naugrim, but if we can lower the ease of entry, perhaps we can get some more help.
User avatar
raevol
Posts: 3093
Joined: 07 Aug 2011, 01:12
Location: Caldera

Re: User Documentation

Post by raevol »

Ravenwing wrote:Does anyone think it would be beneficial for me to write a tutorial on how to get up and running to contribute to documentation? It doesn't sound like you're having too much difficulty Naugrim, but if we can lower the ease of entry, perhaps we can get some more help.
Yes, this would be awesome.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: User Documentation

Post by Naugrim »

Ravenwing wrote:In regards to 1) do you mean any tools for WYSIWYG editing that saves into .rst format?
If so then I'm not aware of any, but I didn't look too hard. You can use this to preview in real time what you're typing. You can also see it on GitHub once you push to your working branch, but this can be a tedious way of previewing and it mucks up your branch history. Psi29a gives the best recommendation, as it will let you preview your inter-document links (what I usually have the most trouble formatting correctly) and is the most rigorous. However, if you don't want to deal with setting that up, the first link is probably your best bet.
Thanks for the advice, really. Just to add some context, I am a 10 years experiences (mainly back-end) JVM developer and contributor to other GitHub projects. I am familiar with documentation tools and in fact I am finding myself enjoying a lot writing docs :D.
So, in terms of tools I usually work with IntelliJ IDE which has great support for Markdown and Asciidoctor in terms of highlighting and live preview. But the support for reStructuredText is not as good. However, as long as it has basic color highlighting, tab/spaces formatting and git integration is fine for me. Some time ago I setup an environment using Docker, basically the same as having a virtual machine. I'll think I'll go that way.
Ravenwing wrote: Does anyone think it would be beneficial for me to write a tutorial on how to get up and running to contribute to documentation? It doesn't sound like you're having too much difficulty Naugrim, but if we can lower the ease of entry, perhaps we can get some more help.
Definitely. Maybe a quick start guide for non-techies, later on we can add sections for more advanced stuff.
I am advocate of "roll out and evolve", once we have the docs in GitHub is really easy to refactor and change them.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: User Documentation

Post by psi29a »

Naugrim wrote:So, in terms of tools I usually work with IntelliJ IDE which has great support for Markdown and Asciidoctor in terms of highlighting and live preview. But the support for reStructuredText is not as good. However, as long as it has basic color highlighting, tab/spaces formatting and git integration is fine for me. Some time ago I setup an environment using Docker, basically the same as having a virtual machine. I'll think I'll go that way.
^5, I use PyCharm for my python dev work and CLion for my C/C++ work (also includes stripped down version of pycharm). The support for MD and the rest is good. ReST plugin still needs love, like a preview window that MD plugin has.

No need for Docker, just use virtualenv.

Code: Select all

virtualenv venv
source venv/bin/activate
pip install sphinx # and other deps as necessary
cd docs/source
make html
Done and done. :)
Post Reply