Any resources on how to start writing documentation for an open source project ? (kbin.earth)

submitted 3 days ago by PandaInSpace@kbin.earth to c/opensource@lemmy.ml

13 comments fedilink hide all child comments

I've been thinking of contributing to foss projects with more than testing and bug reporting. I want to contribute to mainly open source game engines. There are a few that are mature and underrated, but lack any documentation for a user to get started. This is why I decided to do documentation, but I don't know where or how to start.

Is there any general rule/guidelines for getting started with this ? I'm looking for anything that can help a beginner documentation writer

top 13 comments

sorted by: hot top controversial new old

[-] Kory@lemmy.ml 2 points 2 days ago

KDE has a lot on documentation, maybe you would get some inspiration of how this can be done: https://community.kde.org/Get_Involved/documentation

[-] PandaInSpace@kbin.earth 2 points 2 days ago

This is also a really good resource, thank you for sharing. Idk why I didn't think about KDE apps docs before making this post. Thanks!

[-] slazer2au@lemmy.world 10 points 3 days ago

So they have existing documentation? If so see if they have a style guide for how they want info presented. Assuming you are writing to official docs.

You can also look at other projects how their info is presented

[-] PandaInSpace@kbin.earth 2 points 2 days ago

There's nothing other than a basic readme with build instructions. I guess Godot docs might be a good place to start. Thanks!

[-] melsaskca@lemmy.ca 6 points 3 days ago

You need to Jack Webb that shit and stay away from flowery prose. A good resource is to read all of your household electronics manuals with a critical eye.

[-] PandaInSpace@kbin.earth 2 points 2 days ago

Idk who Jack Webb is 😅, but I agree with you, I'm not thinking of flowery prose, but basic steps and instructions for a beginner to get started. Thanks!

[-] melsaskca@lemmy.ca 3 points 2 days ago

Jack Webb was a detective on an old 1950's series called "Dragnet". Often, when interviewing people during an investigation, they would start editorializing and he would always stop them and say "Just the facts, ma'am" or "Just the facts, sir". I'm old and my references are old. Good luck and all the best!

[-] HelloRoot@lemy.lol 6 points 3 days ago

You can often search for "[your topic] university pdf" to find good resources.

Here is one of the results I found searching "technical writing university pdf"

https://prowriting.web.illinois.edu/wp-content/uploads/2024/07/Open-Technical-Writing_-An-Open-Access-Text-for-Instruction-in-Te.pdf

Maybe there is more when searching for "writing documdntation university pdf".

[-] PandaInSpace@kbin.earth 3 points 2 days ago

That's actually a great suggestion. Thanks for sharing that book as well, it appears to go really in depth.

I'll try searching and will update the post with any good resource I find as well

[-] invalidusernamelol@lemmy.ml 2 points 2 days ago* (last edited 2 days ago)

If you want to write something user focused, Rust by Example is a great template to use.

A series of self contained lessons that all build on each other.

If you're doing it for a game engine, you'd probably want to start with the GUI, then some basic scripting (that can go much deeper, but I'd keep it short and share other resources). Once that's out of the way, show some examples of how to import assets, how to manage a project directory, etc.

Keep all of this contained within the framework of making a simple game, so when the reader completes the tutorial/documentation, they have something that they can actually show off.

I also like the Odin docs since it's all one page and shows you features in order.

[-] PandaInSpace@kbin.earth 2 points 2 days ago

Really like the Rust example, might use that as a template. I am thinking of using a simple pong game to get started. Thank you for all the suggestions as well.