search

MovingBlocks / Terasology

Terasology - open source voxel world
http://terasology.org
Apache License 2.0
3.69k stars 1.34k forks source link

A consistent strategy for documentation #5148

Open BenjaminAmos opened 1 year ago

BenjaminAmos commented 1 year ago

Summary

Terasology's documentation is currently spread-out over several different locations using a mixture of docsify and GitHub wikis:

In general, the more documentation there is, the harder it becomes to find what we're looking for. Having multiple locations to search also makes it more difficult to find useful information when needed.

Engine documentation

Engine documentation is primarily found on the wiki. GitHub wikis have some limitations and can quite easily become disorganised due to their flat structure. Hierachies are enforced through listing pages on the sidebar, although this requires people to update the sidebar manually whenever a new page is added. There is a lot of useful content on the wiki but most of it is not referenced from the sidebar, for example the Documentation Guide.

Alternative: In-repo documentation

An alternative might be to move the documentation directly into the repository (under the docs/ directory). We could then publish it using GitHub Pages, possibly using docsify or a static site generator (so long as it is consistent).

Pros:

Cons:

Alternative: Improve the wiki pages

We could also continue to try and improve the state of the engine wiki, possibly by rearranging pages and adding information that was previously missing.

lokytech5 commented 1 year ago

hello am from MLHhackathon open soucre week. could you provide a sample of how you want the documentation to be structured

jdrueckert commented 1 year ago

Hi @lokytech5, actually that's what we want to discuss in this issue. As mentioned in the issue description, we already have various places of documentation and with that also various ways of how this documentation is structured. What we need to figure out is how we can structure the documentation we have in a better way to make it easy to navigate for different types of users and easy to maintain.

lokytech5 commented 1 year ago

Going through the documentation, I can provide you with a sample of how I can make it easy to navigate.

jdrueckert commented 1 year ago

@lokytech5 sure, feel free to propose something, then we can discuss :slightly_smiling_face:

lokytech5 commented 1 year ago

please note. I will be using actual markdown throughout the sample.

lokytech5 commented 1 year ago

Table of Contents

Introduction

The Terasology project was born from a Minecraft-inspired tech demo and is becoming a stable platform for various types of gameplay settings in a voxel world. The creators and maintainers are a diverse mix of software developers, designers, game testers, graphic artists, and musicians. We encourage contributions from anybody and try to keep a warm and friendly community and maintain a code of conduct.

Community

If you want to get in contact with the Terasology community and the whole MovingBlocks team, you can easily connect with us, share your ideas, report and solve problems. We are present in nearly the complete round-up of social networks. Follow/friend us wherever you want, chat with us, and tell the world.

Installation

For easy game setup (recommended) you can use our launcher - download it here.

Minimum Requirements

Alternative Installation Methods

If you already have a Java Development Kit (JDK) installed, you may use a direct download release as an alternative to using the launcher. Java version 11 is required. Direct download stable builds are uploaded here on GitHub while the cutting-edge develop version can be downloaded here.

Development

Requirements

Workspace Setup

To run Terasology from source, follow the Contributor Quick Start Guide designed for IntelliJ IDEA. Note that Terasology workspace is a multi-repo workspace.

Contributing

Detailed information on how to contribute can be found in CONTRIBUTING.md. All submissions must be licensed under Apache License, Version 2.0. If you find errors or issues in any resources, report them using GitHub issues.

License

Terasology is fully open source and licensed under the Apache License, Version 2.0 for code and Creative Commons for art.

Credits

(Credits section)

Contributor Covenant Code of Conduct

(Conduct section)

lokytech5 commented 1 year ago

it can be managed easily but the only drawback I notice is that links need to be updated regularly, I think is better if you have a style guide to follow to maintain consistency, and last but not least, as the documentation grows, the table of content we become complex. Those are just the drawback I notice and I can improve on.

jdrueckert commented 1 year ago

@lokytech5 thank you for the input. However, you seem to assume that this is about our README which in fact barely scratches the surface of our documentation. Please have a look at the issue description and the various places and types of documentation, though, for instance https://github.com/MovingBlocks/Terasology/wiki to get an impression of the amount of documentation we're dealing with.

lokytech5 commented 1 year ago

@jdrueckert, thanks for clarifying and directing me to the documentation. going through it, a lot of information is going on there, with links directing to different sections in the content. Going through the outline, I think if we can group related topics together, then users, players, developers or maintainers can easily find the sections most relevant to them, and beginners won't find it intimidating if they want to get started when going through the documentation. Another approach I still think we make it easy is hierarchical categorization I await your response.

jdrueckert commented 1 year ago

Going through the documentation, I can provide you with a sample of how I can make it easy to navigate.

@lokytech5 For doing so, please consider the individual target audiences (players, developers, maintainers) and what kind of information they would be looking for. Every audience group should have an easy to find entrypoint that allows them to find the most relevant info as fast as possible and navigate to a deeper level of detail if needed. If you have questions or need us to shed more light on the various documentation resources and topics we have and their respective audiences, please ask :slightly_smiling_face:

lokytech5 commented 1 year ago

Thank you for the guidance. Based on our discussion, I've outlined a proposed structure for the documentation that considers our three main audiences:

Documentation Structure

1. Players

Entry Point: A dedicated 'Player's Guide' landing page with:

2. Developers

Entry Point: A 'Developer's Hub' landing page with:

3. Maintainers

Entry Point: A 'Maintainer's Dashboard' with:

All other detailed topics will be nested under these main categories to maintain a clean and hierarchical flow. Before moving forward, I would love to know any specific priorities or topics you think should be featured prominently. Also, Considering the breadth of content and to ensure quality, I plan to work on each section gradually. This phased approach will allow for more focused work, potential feedback iterations, and corrections if needed. Please review the proposed structure and let me know your thoughts. If this aligns with your vision for the documentation, I would appreciate a green light to start working on the "Player's Guide" section as the initial phase.

jdrueckert commented 1 year ago

Hi @lokytech5

I believe the suggested structure make sense as long as we make sure that the respective "landing pages" / "dashboards" are well-accessible for the respective audience groups. From your perspective, what do you think would be a suitable entry point for the three audience groups to get to the landing page / dashboard that's relevant for them?

Also, if you do this, I would request that you implement this using docsify as we started in a subset of our modules already, for instance Health (see especially the docs folder and the resulting documentation) as it allows you to experience the contributor workflow including PRs and reviews and it allows us to easier provide feedback, track the changes and compare before eventually disabling the wiki or rollback to it if necessary (e.g. if the contribution is not completed and we don't have sufficient capacity to complete it. A big concern that we currently have when it comes to migrating the documentation to docsify (or anywhere else really) is that existing links to the current wiki break. Do you have any ideas on how you would approach this problem?

I'd like to discuss your current proposal and any ideas, comments, or concerns you might have on what I wrote above in our weekly reviver meeting on Sunday (6PM UTC on Discord). If the other available revivers are fine with it as well, I don't see a reason not to give you a green light :slightly_smiling_face:

lokytech5 commented 1 year ago

Hello @jdrueckert, I hope you're well. In response to your question, I have come up with the following suggestions to ensure our audience groups have easy access to their respective "landing pages" or "dashboards":

Players:

Developers:

Maintainers:

I also recommend enhancing search functionality to ensure users can navigate to their desired sections easily. Additionally, tailoring the homepage based on user roles or profiles (players, developers, maintainers) could further enhance the user experience.

Addressing the concern of migrating documentation without breaking existing links — while I haven't encountered this issue before, I've done some research. With the pros and cons of each method in mind, I believe a combination of the following approaches might be suitable:

Regarding docsify, I've looked over the repository you shared. I observed that the docs folder contains all the documentation, with each markdown file representing a page. I also noticed that the repository's homepage aligns with the documentation's homepage. While exploring its plugins, many can be leveraged to structure the documentation effectively. However, I will need some time to familiarize myself with its features and plugins. Considering the link issues, creating a custom redirection plugin seems a potential solution.

Lastly, regarding the weekly reviver meeting on Sunday at 6PM UTC on Discord, I'm eager to join and discuss further. Could you please provide details or an invitation to attend? Thank you.

BenjaminAmos commented 1 year ago

I haven't properly caught-up on everything here yet but I can address at least one point.

Lastly, regarding the weekly reviver meeting on Sunday at 6PM UTC on Discord, I'm eager to join and discuss further. Could you please provide details or an invitation to attend? Thank you.

@lokytech5 The discord information is in the project README. Just in-case you missed it:

Documentation is likely to be discussed in the meeting today (6PM UTC).

jdrueckert commented 1 year ago

@lokytech5 First of all, good news. You have our official "go" :wink:

As mentioned earlier, we'd like you to use docsify for the documentation improvements. #5155 migrates the existing documentation in its current state from the wiki to docsify in the docs folder. It also mentions in its description how to locally test it. Until #5155 is merged, you'll need to base any PR of yours on that PR to have the migrated base state available. We'll try to get #5155 merged as soon as possible (once we fixed our infra issues) so you can also work on latest develop.

Looking forward to your contributions! Feel free to work in small iterations and open PRs as drafts as soon as possible so we can check if it's going into the right direction and also have a basis for discussion and answering questions. Once you're happy with your current iteration, you can set the PR to ready-for-review. Explicitly asking for a review on our Discord can help getting faster feedback.

Regarding the suggested access points for the different target groups:

Players:

  • A banner on the documentation's main homepage directing users to the 'Player's Guide'.

How would a player find the documentation's homepage?

  • A clearly labelled "Start Playing" button or icon on the homepage.

What exactly would that button do?

  • For newcomers, an interactive guide on the main game page that introduces basic mechanics.

Gameplay mechanics are very dependent on the activated modules, which is why this kind of documentation should be in-game rather than outside of the game. At most, more detailed explanations could be in module documentation, but not in the main (engine wiki) docs... At some point in the future, module dosc should be integrated at least to a degree with the main (engine wiki) docs, though.

Developers:

  • A dedicated "Developers" tab in our top navigation leading directly to the 'Developer's Hub'.

I'd propose to already engage the different target audience groups on the main page of the docs for easy navigation to their "documentation hubs".

  • Engaging code snippets on the homepage to draw attention to development sections.

What do you consider an "engaging code snippet"?

  • A regular "Developer Updates" section highlighting new features, modding opportunities, and other relevant news.

We do have that in the form of release notes and blog posts, the former of which could be considered documentation to a degree while the latter is outreach. I don't think this kind of information should be part of the (engine wiki) docs.

Maintainers:

  • A direct link to the 'Maintainer's Dashboard' in the website's footer.

Why in the website's footer? :thinking: I would expect people that visit the website to rather be interested / first-time players and developers rather than active maintainers... wouldn't you?

  • In our navigation sidebar, a section explicitly labelled for maintainers for easy access.

:+1: Same as for developers, I would already link to that section from the main page of the docs.

  • Alerts or notifications on the homepage for any critical updates or changes that maintainers should be aware of.

That, again, is not really documentation. But communicating critical updates or changes (for instance current blockers or required actions etc) is an important and relevant topic. It's just out-of-scope for this documentation-focused issue :wink:

Regarding the broken link concern:

  • Retain Original URL Structures where possible.

Absolutely, that will at least help with relative links within the wiki/docs.

  • Use 301 Permanent Redirects for content that needs to be moved. This can be combined with a link map to ensure comprehensive coverage.
  • Implement an enhanced 404 fallback page to guide users back on track if they encounter broken links.

We actually don't have too much control over that. Anything hosted on GitHub pages will probably also drop HTML redirect logic for safety reasons. Naturally, we can check what's possible and what is not.

  • Engage the Community: Let the community spot and report issues as they use the documentation. We can then quickly address such reported issues.

We already encourage that. All docsify pages should also have an "Edit on GitHub" link at their top to allow people easy access to the underlying resource and creating a PR with changes.

lokytech5 commented 1 year ago

Thank you for the clear instructions and the green light on this. I am currently reviewing PR #5155 and am familiarizing myself with Docsify. I'll begin working on the documentation improvements in small iterations as suggested and will open draft PRs for early feedback.

I'll keep an eye on the status of PR #5155 and ensure my contributions are based on it until it's merged. If I have any questions or need further clarification, I'll reach out, especially on Discord, for quicker feedback.

I look forward to contributing and enhancing our documentation!

About the points you raised, I am looking into them slowly and will take care of each of them carefully.

jdrueckert commented 1 year ago

5155 got merged fyi @lokytech5

lokytech5 commented 1 year ago

Hello @jdrueckert, I've looked into the docs folder and observed that there's no index.html file or .nojekyll file present. from Docsify documentation, these are automatically generated by Docsify upon initialization. In your merge of PR #5155, you mentioned transitioning the wiki to Docsify. Before I proceed, I'd like some clarification:

jdrueckert commented 1 year ago

@lokytech5 if you were checking your locally checked-out workspace, please pull the latest changes. As you can see from https://github.com/MovingBlocks/Terasology/tree/develop/docs, both index.html and .nojekyll are present.

Should I initialize Docsify within the docs folder, potentially overwriting any existing configuration? Or would you prefer I manually create the necessary files?

No, docsify is already properly initialized. With #5155 merged, the wiki content is already migrated to docsify, so you can start working directly on the content structure.

lokytech5 commented 1 year ago

Good day, @jdrueckert. I have worked on the homepage, before I make a PR, please kindly go through the images of the new home page I came up with, if it meets your requirements and with your permission, I will create a PR before going to Discord.

link: https://drive.google.com/drive/folders/1aismU43av-mgVyZ_q2TuYe1gh0Ic9hth?usp=sharing

I am currently working on the player Guides. i await your reply.

jdrueckert commented 1 year ago

@lokytech5 please just open a PR and I'll review that. No need for an additional roundtrip with screenshots.