Documentation

All discussion on project related documentation including source docs, manuals, and tutorials go here.
User avatar
Atahualpa
Posts: 1176
Joined: 09 Feb 2016, 20:03

Re: Documentation

Post by Atahualpa »

DavidD wrote:
Zini wrote:Because that is not how Morrowind works. Instances are kept in their original cells. We can't change that without breaking a whole lot of stuff (mods, the esp/esm format and so on).
Fair enough :D. Curious design decision from Bethesda
Morrowind is a very static game with only a few instances being moved out of their original cell during gameplay, so maybe the developers decided rather to keep track of these few instances than to implement a more complex management for all instances.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Documentation

Post by Ravenwing »

How are we deciding what type of information goes where within our website and literature? In other words, what goes in our published documentation, and what are we just leaving to the wiki? I ask because I'm currently putting a list of the config settings into the documentation but scrawl thinks that should remain in the wiki for easy of updating. To be honest, I think we could really put everything in the wiki, but obviously we decided not to do that. Since we're including other advanced information, it seems like we would want to include the settings info in the documentation as well.

As a side note, I also don't see why we include info about deprecated settings at all. Nobody should be expecting us to support three versions back.
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Documentation

Post by Ravenwing »

I've included the relevant parts of our conversation, but I think scrawl and I agree now on what should be done regarding this particular issue:
scrawl wrote:Probably not a good idea to duplicate the wiki content. Would be more work to keep information up to date. Either the wiki should link to the manual, or the manual should link to the wiki. Given that the wiki is already complete, I suggest the latter.
Ravenwing wrote:I had thought about that too. To be honest I think all our documentation should be on the wiki. However, if we're doing documentation that's going to be available online and offline, then I would like to have it as complete as possible. Also, our wiki actually isn't complete. There are a large number of settings not included, but I figured it would be easiest to duplicate what's on the wiki first before adding in the rest.
scrawl wrote:Duplication is out of the question. If we merge this PR then the wiki should be deleted and just point to readthedocs.
I'm now leaning towards readthedocs being a better choice than the wiki for settings documentation. So feel free to continue.
Advantages of readthedocs:
  • Documentation in the repo makes it easier to update when a new feature is merged, we can just merge the documentation for that feature in the same PR
  • We have different versions of the documentation for each OpenMW branch/version (e.g. one for git master, one for the current stable release). This is built into readthedocs as far as I can tell.
Advantages of wiki:
  • Lower barrier to entry (everyone can use a wiki, but not everyone knows how to use github).
I'm liking this because like I say in my quote, the wiki is not actually up to date on available settings. What would be ideal is to have the programmer who implements new settings to change the documentation themselves using my format. That way we know it's up to date, and it's being described by the person who made it, so we know the actual effects and limitations of the setting. The only benefit to having this on the wiki is other people can keep it up to date, but technical settings are probably not the best to have randos editing.

And this kind of solves my issue with different versioning. We don't have to include all the old stuff, but if someone is using an old version, they can check their own documentation.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

I'm glad people are really enthusiastic about RTD, it really does solve the versioning problem. :)

The docs are up to date to a specific version of the docs.
User avatar
Atahualpa
Posts: 1176
Joined: 09 Feb 2016, 20:03

Re: Documentation

Post by Atahualpa »

@Ravenwing: Nice! -- But what about the other "user documentation" pages (Native Mesh Format, Fonts, Texture Modding)? Do you want to move their contents to our documentation as well?
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Documentation

Post by Ravenwing »

Hmm, well I'm thinking move fonts to RTD and leave the other two on the wiki. For fonts we're specifically describing how to install them, but for the other two we're kind of giving guidelines on how best to use other programs. Perhaps some of the information should be included in the documentation in terms of what our formats require, but everything else that has to do with using other programs like Blender is out of the scope of what we need to support. The wiki is (ideally) more collaborative, and I think those are both topics that can benefit from being more accessible. I can certainly link to them in RTD though, because it's useful information.
User avatar
Jyby
Posts: 408
Joined: 10 Dec 2013, 04:16

Re: Documentation

Post by Jyby »

jeffreyhaines wrote: I'm loving ReadTheDocs' I think it makes a lot of sense to bundle OpenMW documentation. I believe it will encourage more people to read it. I also think it makes it easier for us to peer review. Centralizing most of the official OpenMW development stuff on Github.

Perhaps we compile the PDF with the images we release or it could be as easy as hyperlinks in the OpenMW launcher or OpenCS menu bar.
Naugrim
Posts: 172
Joined: 08 Jan 2016, 01:32
Location: Spain

Re: Documentation

Post by Naugrim »

Just wanted to make a quick remark on the fact that currently, there's no mention to implementation changes in the current wiki.
I only know of 2, but could be more:
- https://bugs.openmw.org/issues/1751
- https://bugs.openmw.org/issues/3146

While I agree with the changes these can be confusing for new-comers and I think they should have a section in the current and future pages.
User avatar
raevol
Posts: 3093
Joined: 07 Aug 2011, 01:12
Location: Caldera

Re: Documentation

Post by raevol »

@psi29a, this is our corrent landing page for the docs? http://wojciech-mueller.de/openmw_doc/html/index.html

How do we edit that page?
Are we limited to the categories it lists on the left? I'd like to start with, for example, a "directory structure" page that explains the purpose of each directory in the base source directory.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Documentation

Post by psi29a »

I have no idea, this documentation was generated by doxygen awhile ago and hosted by someone else. We have no control over this.

Our official documentation is here:
https://openmw.readthedocs.io/en/master/

If you want to edit it, then you do it on github and make a PR. :)
Post Reply