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
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
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!
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
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.
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
There’s nothing other than a basic readme with build instructions. I guess Godot docs might be a good place to start. Thanks!
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.
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!
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!
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.
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.
If you really want to get into technical writing, you can try to study along with this free course. https://developers.google.com/tech-writing
Haven’t come across this, thank you for sharing! I’ll take a look
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”
Maybe there is more when searching for “writing documdntation university pdf”.
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
