A place for documentation

[oniatus]

We still need a single place for our developer documentation
I will add a poll for the next two weeks to this thread, then start working on the docs again before GSOC 2018 starts.

Overview of existing documentation:
1. Wiki
https://github.com/MovingBlocks/Terasology/wiki

• contains most of our documentation
• content has different quality
• some pages are not structured
• no search function
• markdown syntax

2. Sphinx-based documentation
https://metaterasology.github.io/docs/

• contains a rework of most of the wiki pages
• depends on sphinx and restructured text syntax and needs a jenkins build
• has a search bar
• most people dont know it exists

3. In-repo docs
https://github.com/MovingBlocks/Terasology/tree/develop/docs

• Mix of non-developer documentation like module overview, credits and play instructions
• Markdown files
• Under version control

4. Tutorial modules

• Special topic docs with documentation in the wiki
• Not linked properly (we have 10, only 4 are mentioned in the wiki)

I would like to move the documentation in one visible place and remove all redundant or outdated parts afterwards.
The tutorial modules and the in-repo docs should stay where they are but we could link to them in a more visible way.

My main requirements for a developer documentation would be:

1. Easy to find
2. Easy to navigate (at least a good page index, preferable a searchbar)
3. Easy to edit (syntax should be easy to learn)
4. Under version control, no direct editing without reviews.

I see some options, each with it's pros and cons:
A - At the wiki
+ Easy to find
+ Easy to navigate (-sidebar has to be edited by hand)
+ Easy to edit (markdown)
- Not under version control (behind the scenes it is but there is nothing like a pull-request option)
B - Separate page with sphinx docs
- Hard to find
++ Easy to navigate, search function
- Not easy to edit (requires rst syntax and a local python/sphinx environment)
+ Under version control
C - Inside the docs folder at the engine project
+ Easy to find
+ Easy to navigate (same as a wiki)
+ Easy to edit (can be markdown)
+ Under version control
+ Developer documentation is available next to the code
D - Separate project with markdown pages
+ Easy to find
+ Easy to navigate (same as a wiki)
+ Easy to edit (can be markdown)
+ Under version control
+- Separate from the engine (can be a good or bad thing)

Open for discussion

 

[Cervator]

I pick ... the worst possible option, which isn't even on the poll: all of the above!

Bear with me, I already feel terrible starting such an awful response ...

I've looked at the topic repeatedly and the most clear (if you can call it that) map of my thoughts are at https://sketchboard.me/bzHUxZ2moPgk#/ - may need team access to view, let me know if so. I forgot why it isn't public.

I don't think any one of the options is sufficient on its own, as much as I'd love to have just One True System. There are a bunch of factors in play:

• Super basic intro doc on a repo to get a glance at the purpose (a module.txt, the repo README, or a few minimal extra pages like the engine)
• In development vs latest stable vs past releases
• Change / release notes plus credits
• Per-repo documentation vs org-wide documentation (code of conduct etc)
• Template documentation vs explicit doc for a given thing of a category (inheritance-based doc?)
• Validating documentation vs code (wiki tutorials going out of date vs their paired code)
• In-game documentation vs out of game documentation
• Module indexing sites - what does it index?
• Third parties will end up making their own doc sources at some point (usually spoiler filled and often out of date)

Also, to show just how often this has come into focus and faded again I just found https://trello.com/b/4ntsOi4s/sites-and-docs which I had completely forgotten about ...

The requirements above are good, I would take one step further back and also ask some what-where-why-how primers. What audience is something for?

Introductory

Explain what the thing is real quick and how to use it. Repo READMEs I'm thinking. Short and simple. This could potentially be embedded as a starting point in a later more detailed site (for instance the engine readme is embedded in the About tab on terasology.org)

I'm leaning toward the idea to avoid having any other doc files in a regular repo (so move MODULES, PLAYING etc out of the engine repo). Link to all the things but write the doc in a way so it rarely needs to be changed. Reduce overlap between README and module.txt - maybe in-line some of the metadata from module.txt in the README via automation (and put a hidden comment in the README to not edit that there)

The goal here isn't really to educate the user in detail, but just glance at what's going on and direct to some useful resources.

Some of the basic templates that get magically used for things on GitHub probably would also fall here but maybe not necessarily be of introductory interest. Like Code of Conduct. It kinda sucks because some of those things are org-wide but we don't have a good place to put that - best we can do might be keeping them simple (link to details) so they change less often then include them in the module creation batch of files + prepare auto-magic to validate that they're up to date everywhere

"Would you like to know more?"

For things that warrant more depth (the engine, some modules, etc). Tricky to standardize this

• How do I play the game?
• How to I administer a server?
• How do I exercise content X?
• How can I contribute / customize stuff?

I think we further brainstormed this, maybe based on that Trello thing from earlier. Remember when a few of us did some surveys to better group things as being for players, developers, etc?

You could throw a whole Sphinx style setup into this that covers everything like the dev doc site does but that might be overwhelming for a person just wanting to dip a toe in.

• The first two we have in brief in the PLAYING doc file in the engine repo, which IMHO isn't really ideal, nor do we really extend on it.
• The third is scattered across a few modules that try to explain themselves better, and is hurting from the lack of something centralized like "What is Josharias Survival?" or "What gameplay templates exist and what are they for?" or even the simple "Hey what are modules?"
• The fourth is/was covered in the engine wiki (which again IMHO isn't/wasn't ideal) and most got moved out into the dev doc site, yet then slowly new stuff sneaks into the wiki as we don't have a good workflow for adding new stuff or even where something specific should go

We've talked in the past about having one nice dev doc site (which lead to https://metaterasology.github.io/docs) and a matching player doc site (on terasology.org somewhere). But looking at something like the landing page at https://metaterasology.github.io/docs is pretty overwhelming. We need a more gentle intro and this would be the layer for that while the dev doc (and player doc) sites might go to the next section

This would help you find individual tutorials, but not necessarily be the tutorials. It would describe what gameplay templates are but not exhaustively detail them. In other words if the first sketch I linked is the brainstorm of all the things maybe this layer is https://sketchboard.me/tAlG29BYVSTN only with a split between contributors and players (that sketch is solely a contributor's potential journey)

I suspect there would be multiple entry points that could lead to this

• Links from the READMEs
• Links from social media
• Referrals from friends / the web
• Person arriving with an interest from the gameplay side (saw first on YouTube)
• Person arriving with an interest from the code side (saw first on GitHub)

All could lead to one of two landing spots: the home page for the player site (terasology.org) and the contributor site (metaterasology / terasology.io). Right now on terasology.org the home page is blog entries, maybe we could move that to a tab and instead have something similar to the redesigned setup (was floating around in #outreach on Slack for a while, but naturally archived by now) with easy boxes for "Where would you like to go today?" with a nice toggle button to go between the terasology.org player site (light theme?) and the terasology.io contributor site (dark theme?)

"Tell me ALL of the things!"

Probably the default sections here should target the most recent stable release, and not change between releases. Ideally it should be easy to make pending changes that show updates and then auto-push that on release to the proper site. I'm somewhat pulled to the idea of using wikis for develop (draft changes) then auto-publishing with releases for versioned docs, maybe in a Sphinx-like setup powering a full GitHub page. Plus somehow extracting change notes from that process to post on a Release page on GitHub.

As much as I love the current look and feature power of Sphinx it breaks my heart that it is a different format :/ Although the GitHub wikis do actually support other formats than Markdown, including reStructuredText but that disables the easy wiki editing tools I think ...

Good examples are the tutorial repos. Step by step simple wiki pages that bring the user through whatever topic, hosted in a tutorial repo dedicated to said topic, maybe even depending directly on the module that implements the topic.

Playing the game on the other hand? Where does deeper info for that even logically go? Typically that'll involving multiple repo-level topics. Maybe you could introduce something like JoshariasSurvival in the repo that hosts the gameplay template definition.

• Actual module tutorials
• What's currently in development? Show me the cutting edge!
• Technical details, like the full Modding API list of events, systems, etc. This calls for something Sphinxy and could show both engine/core level details and extended details from module land (new events in a module may not technically need @API but would be useful to highlight)
• Javadoc, both auto-linked from within the Modding API, available from Artifactory for IDEs, etc
• Credits for everything including every individual piece of artwork including license details
• Full module indexing site with metadata and so on
• All basic key bindings and what they do (automate it!)

I have a warped desire to somehow drag the engine-libs concept into this as well to somehow split the huge chunk that is the engine (in a documenting sense) into smaller chunks .. But I've been editing this on and off for a couple hours and it is large enough as it is. To be continued, initial feedback appreciated ...

(Edit - of course: I bet we could put the "user journey" in the second sketch in one of the tabs on either site, with a multi-step "Click what interests you" to then readily guide the user to the right resource. I bet there's some web wizardry that would make that pretty. On the dev side maybe that could include the "Here are some easy starting issued pulled dynamically from all the repos on GitHub!" thing)

 

[Cervator]

Thoughts kept churning so I started sketching a new thing: https://sketchboard.me/DAUNYYeXLFHi - still rough

Using a module repo as an example at the "Tell me ALL of the things!" layer, possibly a tutorial module. Includes versioned docs, API notes etc, although I don't exactly know what the GitHub page would look like. Something Sphinx like I guess?

Jenkins scans for stuff like API docs, validates code snippets on wiki pages, writes out a changelog page in the wiki with plain commits, every build (not spammy since wiki repos don't send notifications). User can manually tweak things to make them look better. At release time get a little report of what's going on paired with a release gate in Jenkins, also two PRs in the module repo (develop -> master + updates from wiki -> gh-pages)

Approve and the PRs get merged, a release happens, and the GitHub Page gets built. Something similar could probably work for the engine repo ...

That doesn't do anything for the "Would you like to know more?" layer, which we don't really have right now. But it would make use of the wikis yet also give us a gh-pages setup in every pages that could use something more fancy than the base wiki setup with some extra markers or so plus automation in Jenkins. Would depend on what tech and options we might have.

 

[jellysnake]

So for me I like to think of "documentation" as having two main types.
Player, and Developer.

I think from a practical standpoint I would ideally see the layout structured like such:

The Main Developer Site
This would be a site that would be the go-to destination for a developer. If someone was trying to develop a thing then it would be here that they go. It would have a two main sections each with a specific purpose.

The guides section
This would be half of the stuff that's currently on https://metaterasology.github.io/docs/ merged with a lot of the content from the Tutorial Repos. It's guides on how to use systems and functionality currently present in the project. So the getting started guide would be here; a guide on making a new module would be here; NUI guides; guides on making a new block family; you get the idea.
This would also have guides for module features integrated as well. For instance adding a new plant using SimpleFarming. Using the Inventory (as core is technically a module).
One side note for this section is that I would also move all the content from the wiki's of tutorial modules to here. I feel that maintaining the code of the tutorial wiki's is integral to a tutorial, however they are too spread out at the moment. I think that they should be integrated into the main docs more, rather than being very hidden at the moment. The only way one can find them is if they know that they are looking for that particular module because of their odd location.

The listings section
This is essentially the javadoc with a few extra features. It's purpose is to list out all the features we have in an easily searchable method. For instance, a list of all events, a list of all components, a list of all 'Managers" (InventoryManager, EntityManager) etc etc. These would be in an easily searchable format which then links to a full expanded list of that items features, easiest to probably have that be the javadoc page for that class.
I would also be interested in seeing if we could integrate the javadoc into the same site, formatted nicely.

Within each of those two sections both engine level and module level content exists. On a technical level we could have the docs stored as a part of the module itself and then displayed in the main site seamlessly. This could even be achieved by simply duplicating the docs content from the module to wherever the site is hosted. It would be trivial to listen to webhooks of the module being updated and then to update the content on the duplicate storage to match.

The Main Player Site
This is where players go when they want to know something. Ideally there should be no overlap between this site and the Developer site, but instead plenty of links between the two. The easiest way I mentally distinguish between the two is "Does this information concern the front facing content or the systems that implement this content?" This player wiki is much more similar to things like the Minecraft wiki, the Factorio Wiki, the ARK wiki the Breath of the Wild Wiki and so on. In this wiki the split between module content and engine content is much more obvious. This is partially due to the player not interacting with the engine anywhere near as much (ideally not at all) because all the content is in separate modules.

The Module Sections
Each module would have it's own section. The sections would deal with the information relevant to the module itself. So for instance, the Inventory module would have a section and this would include things like how to open the inventory, how to move items around. The Edible Flora module would have a section and it would contain stuff like how to grow a plant and which plants you can breed together. All the sections would be incredibly interlinked, with the Edible Flora wiki containing links to Genome on how to breed plants together for instance.

A key feature of this should be that it is publicly editable there on the site itself. In this way, players of the game can easily add information and maintain the wiki. Unlike the developer docs, this shouldn't be contained within the module source. Rather it should be linked to in the module.txt files and other places that the player will interact with the selection of modules.

Technical Overview
I will readily admit that I don't know how hard and or easy it would be to create something like this. I imagine that continuing to use Sphinx docs for the developer site and then using webhooks to pull content from the modules (and perhaps changing it's format) would be the best method. It would be fairly simply to automate sections of the documentation in this method, which would be useful for things like the list of events and the like. Indeed for the second section, the majority of the content can be automatically generated.
For the player site it would could simply be easiest to use MediaWiki, which is the format the majority of game wiki's use. It is possible to edit pages using API so for official modules we could allow things like automatically scraping recipes or similar. We could perhaps also find a way to limit which pages a set user can use the API on, thus allowing third party modules to also automate similar things for their sections of the wiki. This however is probably a ways off, as that would require us to have third party modules first.

For the issue of editing Sphinx docs in particular, if we are already pulling content from a module repo we could simply store it in the markdown format on the module sections and then parse it into rst Syntax for displaying on the docs itself. This does then seeming limit any advanced features of rst, however we could also allow modules to store docs in a .rst format as well as .md, only converting the latter when we find it. Alternatively we could extend markdown, or simply embed the rst, which wouldn't display in a normal markdown reader but would render fine on the docs site.


In conclusion I feel that, for documentation, having a centralised site means it's much easier to use, access, and I would argue, edit the docs. Things like what to contain in the readme's is a subtly different issue, as it's fairly obvious that one shouldn't try to contain all their documentation within that one file.

 

[Cervator]

Thanks for the feedback Jelly

I've been doing a lot of thinking over the last few days as well as some experimenting. It has gotten me to consider three high level topics involved here:

• The split between dev docs and player docs (two different sites)
• The technology used behind the scenes to display the docs and the features provided
• The structure, automation, and process helping tie it all together and get everything as close together as possible (to avoid "drift")

Especially the second and third item are fairly independent and my personal interest is more in the automation, naturally, as a logistics kind of person.

I started looking at the tech itself considering something like sbt-microsites vs Sphinx (and vs plain GitHub Pages) but I came to the conclusion I was looking at the wrong thing as that's not my expertise nor necessarily something I can champion. When you dig deep either tool can be tweaked in the ways important to me when it comes to the structuring and automation, and both have pros and cons. There are certainly even entirely different options we might want to consider. Both format approaches (Markdown (MD vs ReStructuredText (RST)) show roughly comparably on the final GitHub Page to regular view as files in the GitHub Repo and even as a page in a GitHub Wiki (although edit options on GitHub favor MD)

• Sphinx has the search option which is indeed more powerful. It also has deeper site navigation options (nested topics) and can more readily support a single larger site with more pages. There are some plugins but I haven't dug very deep
• Microsites has a plugin allowing in-line syntax validation and interactive code, which is a very powerful way to write tutorials (more important for devs, but could also work for players - imagine an OpenComputers type syntax checker on a tutorial page). Seems like it works by pulling markdown out of actual code files to use as the text then the methods become the interactive code examples (but ... heavy emphasis on using the Scala Build Tool as part of that, can't use Gradle)
• Plain GitHub Pages can enable some basics like a sitemap via Jekyll plugins. And for that sake who knows what other plugins are available there, I see one also supposedly supporting search but who knows which still function when deployed as a Page (needs to be all static). Also a code snippet displayer for code right in the associated repo. And some localization, maybe.

Focusing instead on the structure for a bit the main thing that occupies my mind is scale and maintainability. It might be "easy" enough to spin up a Sphinx setup like the current one for dev docs, but if you project out years in the future when there is far more content any sort of centralized site that tries to cover more than the basics will struggle. I think we need a way to embed more of the specifics into the code repos themselves, for both the dev docs and player guides.

Two additional things come to mind: in-game documentation and internationalization. I want as much "one true source" as possible for all documentation. So what better way than to shove more of the docs into the repos that provide the logic systems and content? Recently there has been some talk about the InGameHelpAPI system and optional dependencies, specifically moving to optionals instead of splitting API and help activator modules.

Lets look at an example: Josharias Survival. At present I'd say there are two major sources of help there, and I'll throw in the Journal entries from TTA as a third and pretend something similar exists for JS

• Recipe listings: there is a navigable system for looking at all registered recipes, the involved ingredients, and nearly a way to better explain the involved processes ("this thing needs heat", etc)
• Helpful tips: when you start you get a couple popups about how to access the help system (with the recipes) and the skill training system. Those systems in turn have typical in-UI simple help text
• Journal entries: essentially bigger timed versions of the helpful starting tips. When you acquire certain resources or encounter things (say a creature) a larger journal entry can appear to help explain it in deeper detail (either objectively or in-character)
  • A potential variant of this would be finding outright in-game books that explain things, like the starting book you now get in NeoTTA

Earlier I mentioned wanting to do more scanning during code builds, and that features prominently on the most recent sketch I made (still a pretty rough draft). Targets would be API docs, keybinds, credits and other dev/contributor type things, but you could also scan for content. Say our venerable deer gets more help/metadata added to it and this gets pulled out during a code build. That right there could become the "wiki page" for deer. Look at creature pages for ARK, like the Raptor - a ton of that info is data mined anyway.

Any sort of player-edited MediaWiki for Terasology will end up the exact same way, including inaccuracies and out of date info. Why don't we just plan to post the meta-data ourselves if somebody really wants to look it up anyway? We could still let players theory-craft strategies separately. Just keep our data objective and consider not scanning for lore / secrets. I would suggest we should outright disallow editing in later stages like that as it is a recipe for "drift" - but instead make the process easier to submit edits directly against modules (possibly via the individual wikis, which will then be caught up later by the automation)

Same thing for a given crafting system. Embed all the help docs right in the code module. Maybe even the dev tutorial stuff for how to extend it. While we're at it consider one day finishing our internationalization to include entries in prefabs then translate even the help text and add the tiny little flags on the sites to switch display language. Use dependencies in module.txt and decorators in the in-game help system to make links to other related modules, like how in Javadoc you have a few magic tags to create links and syntax highlighting.

During code builds scan out all the stuff, both dev and player doc, summarizing some details on draft/review pages in the wiki repo. As on the diagram when a contributor decides to do a release they review the prepared stuff (like provide better change notes on a wiki page), click a button, and the automation does some stuff:

• Merge in latest translations from the weblate branch
• Creates a PR from the develop branch into the master branch so you can see the code changes for the release
• Creates a PR from a gh-pages-develop branch into gh-pages so you can see the documentation changes for the release
• Maybe establish a pre-release / release candidate entry on the GitHub release page

At this point there is a release gate in Jenkins and the contributor has a final chance to review, especially paying attention to the code PR vs the doc PR to better encourage keeping the two of them in sync. Some of the scanning should also be able to detect when something isn't covered by docs, say if a new item is introduced but it lacks help text.

On final approval everything is merged, the release is published on GitHub and in Artifactory, and any additional module metadata is submitted to an index that can be used by aggregator sites like the meta server for in-game listings, a module summary site, or even a gameplay template page on JoshariasSurvival that'll be categorized to show up in a list on the main player doc site elsewhere.

Probably a bit crazy and still a design in progress to say the least.

I have pending work adding Groovy utility support for having the wikis repos and even the gh-pages branches living in a dedicated spot in a workspace. That would also allow easy searching, maybe even bulk refactoring to catch more instances of things being renamed and such.

 

[manu3d]

I have the suspicion @oniatus is not overly happy with how this thread has expanded to a much broader documentation scope compared to what originally intended.

I'll stick to the original topic by saying: for developers I'd much prefer to stick to GitHub's wiki, to avoid further tool fragmentation, but I'd make much more visible linkds to the automatically generated javadocs.

It is true it is GitHub's wiki is a limited tool, i.e. in terms of versioning and search. But if the wiki is reasonably well structured (and it's not that bad right now, structure-wise) searching is less of an issue. I see the wiki more for high-level information and the number of pages in it should never grow huge - again, searching is less of an issue. And versioning, yes, it's rudimentary, but it is there and it does allow for easy diffs and reverts. Low-level information such as javadocs are more of an issue but I'm guessing the html javadocs have search functionality on par with most other javadocs tools out there?

That been said, I won't make a fuss over the specific documentation tool: I'll use whatever you guys think is best.

 

[Skaldarnar]

What @manu3d said

I'm in favor of the simple capabilities the Wiki offers, but I'm happy to adopt whatever the majority agrees on. Most importantly, I'd like to reduce the clattering of documentation over multiple locations.