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

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

15 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 15 comments

sorted by: hot top new old

[-] Kory@lemmy.ml 2 points 1 day 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 1 day 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!

[-] farooqkz@realbitcoin.cash 1 points 1 day ago

In general if you want to be a good writer, you need to be a good reader first :)

Writing is a good ability you could have so you would be a more valuable person, and also create value. Also writing is a way to express yourself, like in your blog.

Like many other things, you get good by practice. If you enjoy doing it, then just go read and write. Ask for feedback. You'll get better and better slowly :)

Also may the Source be with you :D

[-] PandaInSpace@kbin.earth 1 points 1 day ago

Damn wasn't expecting this to get philosophical lol. Good points, I didn't think of documentation through this lens, I was just thinking of writing basic instructions, which might not be as easy for a beginner to understand.

My initial idea was just to use a blog, but it might not be easy to find for people new to the project and having docs as a repo might also allow the devs to change anything when they want as well.

[-] melsaskca@lemmy.ca 6 points 2 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 1 day 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 1 day 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!

[-] slazer2au@lemmy.world 10 points 2 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 1 day ago

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

[-] invalidusernamelol@lemmy.ml 2 points 1 day ago* (last edited 1 day 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 1 points 1 day 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.