This document provides guidance on writing documentation for Buddies of Budgie. This is not intended to be an all-encompassing document, however it will strive to provide links to any extra resources to make your documentation writing as easy as possible.
What Should Be Documented?
Buddies of Budgie documentation is intended to cover the following:
- Day-to-day usage of Budgie Desktop, with useful information to new and existing users alike. This can be everything from keybinds to how to install Budgie Desktop on various operating systems. It is not intended to replace documentation for those specific operating systems or any applications those operating systems / curated experiences provide, but useful guidance on navigating around various "core" Budgie Desktop functionality and features.
- Developing Budgie Desktop or "on top of" the desktop with our panel and Raven widget APIs.
- Information about the organization, how it operates on a daily basis, and how one can get involved in the organization (not even necessarily coding!)
Before Getting Started
If you would like to write some documentation but aren't sure where to start, our recommendation would be to take a look at our issue tracker which may have requested documentation.
All of our documentation, including the site itself, is open source, meaning you can take a look at how it all works under the hood!
If you have an idea of some documentation to write, we suggest taking a look at the issue tracker linked above or see if someone else had a similar idea by taking a look at our pull requests.
Writing documentation requires some technical knowledge, but it isn't anything we believe you can't learn if you haven't already! In some cases, issues can just be solved with some copy / paste and editing.
The process of writing and submitting documentation requires that you "fork" our GitHub repository linked above. Forking is effectively creating your own copy of all of our source code (e.g. the website) and docs (like this one!). To do all of this, you will need an account with GitHub, the collaboration platform we use for issue tracking, source code management, feature requests, and more.
GitHub accounts are free and you can create one just by visiting their sign up page.
Have an account? Great! Now it's time to do that forking we talked about. Just click here and you should immediately be greeted with a page with pre-filled details. Make sure the owner is you, then click "Create fork".
You will need to now "clone" your fork to your computer. There is a bunch of different ways to do that, from the command-line to various graphical programs. Given that fact, we would just recommend you check out GitHub's documentation.
Of course, testing out your changes will require some technical knowledge, but our README should help walk you through that. You can read it in your fork too!
You can reach out to us on our Matrix Space for guidance if you run into issues.
Documentation is written in either GitHub-flavored Markdown (GFM) or MDX. Chances are, you will be writing your documentation in GFM, so we will stick to that for documentation. For really fancy docs, be sure to take a look at Docusaurus' Markdown Features.
- Figure out where the doc goes. Is it something related to development workflow? Put it in
doc/developer/workflow. Related to the end-user? Probably somewhere in
docs/user. If you aren't sure, that's fine, we can always move the file later or invent a new category.
- Create a file in the respective folder with the file extension
.md. For example, "Hello World" should be all lowercased with spaces replaced with
- Create the header of the file. There is a lot of "front matter" options, but just stick with the basics of a
descriptionfor now per the linked documentation for Docusaurus.
Once you do that, the recommendation is to run Docusaurus on your local machine following our documentation linked in the README of the repository. This will provide you a live preview of the documentation and how your doc will look in the live environment for the rest of the world to see.
After that, just start writing!
Submitting a Pull Request
Submitting a pull request can be done through our GitHub repository. GitHub has excellent documentation that can walk you through this process. Since you will likely be working on a "fork" of the repository, it is recommended to follow GitHub's documentation on creating a pull request from a fork.
Docusaurus supports adding assets, such as images, to a document. Please keep assets in an
assets/document-name-here folder relative to the Markdown file.
We would expect assets for this document, located at
docs/developer/documentation/writing-documentation.md to reside in
docs/developer/documentation/assets/writing-documentation. We have an example below for reference (and testing!)
Transparency should be used sparingly as our documentation center supports both light and dark theme. Using images that look good against a light background may make them unreadable on a dark one, and vice-versa. You can use Themed Images in MDX, but consider if that is necessary first!
Images should be compressed without noticable artifacting, preferably in JPG.