Getting started as a contributor, anyone have suggestions for where the docs could use help?

I’m hoping to contribute to Lubuntu as a documentation writer. I really enjoy writing software documentation, and I really like Lubuntu, so why not put the two together? So far, I’m on the development mailing list, I’ve registered my Libera.Chat nickname, I’ve made a Discourse account, and I’m learning reST. I’ve also requested a Phabricator account (or rather, was basically offered one by @guiverc, who was extremely helpful getting me set up to contribute), so I think I’m all set as far as the technical end of things go.

Where would be a good place for me to start writing documentation? Are there any TODO areas that need filled in? Are there new applications, features, or processes that need documented? Should I be looking for and fixing errors? I don’t necessarily have to write documentation for the Lubuntu Manual - I’m fine with making documentation for whatever other things need it, if that would be useful.

5 Likes

Apologies for the delayed response.

I think you have already made some great steps towards contributing. The workarounds you have presented have pushed us developers to identifying resolutions to those problems.

Back to your question. I think the biggest step is to just stick around (which you have been doing). If you want to help with the manual and contributing there, identifying and proposing fixes is a good start. Adding tips and tricks for things beyond where the manual goes is probably something that could use more documentation. We have a few of those here in Discourse but I think it is an area we could expand on. The manual guides you well to where things can be changed but knowing how and why folks make changes from the defaults could be helpful.

Wherever you settle in to contributing it is greatly appreciated. We are a small team but we work together closely. Some of us are stretched between a few things so our availability can be limited (case in point my delayed reply). Don’t get discouraged if some of us can’t get back to you right away. Having some overlapping contributors goes towards project sustainability.

5 Likes

Thank you so much! Good to know that tips and tricks are important - I have an guide on enabling RAM compression that’s almost finished, but I stopped because I thought, “well, people could find that info lots of other places and maybe we don’t want the docs loaded with stuff that’s not Lubuntu-specific.” But if that’s actually a good area to work on, that’s great. I also love your idea of documenting the whys and hows of setting changes.

Don’t worry about delayed responses - if anyone gets being stretched between a few (hundred) things, it’s me.

5 Likes

I really appreciate your effort.

I have been using free software (or whatever name you might give to it) for at least 25 years. I also happen to be a (retired) software engineer, with a keen interest on Unix/Linux operating systems. Considering that it would be nice to help the team which enable my favorite OS (yeah, Lubuntu), I am tempted to join the team like you did. Unfortunately (sic) summer has arrived in the part of the world where I live. Unlike in the late autumn and winter period, I’ve noticed that I am right now lacking sufficient time to be of any serious help.

I am aware that communication of the Lubuntu in-crowd takes place on chat channels. Before I set up shop (like you did), @Team it would help me, and maybe you as well, or others, to have some kind of prioritised roadmap of what stuff is required in the near future, or what is just nice to have or a general feature request.

4 Likes

Very nice write up.

And this just a suggestion not an ask or demand:

A nice detailed write up on Zswap would also be useful as I prefer Zswap for my old hardware (1Ghz proc w/ 3GB memory) over Zram because the performance penalty of compression/decompression is only done when needed with Zswap. Zram always has performance penalty of compression/decompression.

And note with 5.16+ kernels zstd can be used instead lz4 for compression with either Zram or Zswap.

3 Likes

I’ve been watching and have seen OP’s contributions.

One thing I’ll note is that while you write well, your writing is too personal for documentation. Technical writing is much different (and I don’t prefer doing so) than other kinds of writing.

We should probably have a formal ‘Style Guide’ for documentation, but I don’t believe we have such a thing. There’s this section in the Ubuntu Wiki but it is outdated, incomplete, and itself needs work.

Other than that, and that’s a bit petty, carry on the good work.

4 Likes

I see what you’re saying. I dislike much technical writing because of how awful it is to read through it. I kinda got used to the “For Dummies” style of writing (I love their books). But my style of writing looks more like it belongs on a Linux Tips site (like your site). I should figure out how to strike a balance between “wow do I really have to read this” and “ok ok this is a manual not a blog”.

6 Likes

Didn’t even know zswap was a thing! That’s cool, thank you for showing me that! I will definitely look into it and see if I can make a guide.

5 Likes

That’s a good example. I’m very informal and chose that style at the start as doing that much technical writing would have meant I burnt out within a month. Technical writing is an art in and of itself and the diligence is, in my opinion, a necessary element. It’s a tedious sort of thing.

1 Like

I used the following site as reference. I believe this process is the same for any apt (Debian based ) Linux distribution. Enabling z3fold is a nice compression ratio improvement also.

zstd is likely best compressor/decompressor in most situations but requires a 5.16+ kernel. I’m currently using latest 5.17.7 mainline Ubuntu ppa kernel:

https://kernel.ubuntu.com/~kernel-ppa/mainline/v5.17.7/

I use a tool called mainline to easy manage adding and removing kernels. I prefer the command line
mainline interface but the GUI is slick.

4 Likes

OK, took a swing at technical-but-not-awful-to-read writing with the “Running Windows applications on Lubuntu” guide. How’d I do?

1 Like

That is less informal than before, but still fairly informal - but probably not too much. You rely heavily on “you” and I spotted at least one instance of “I” - which should never be used in formal writing (or journalism, but that boat sailed a long time ago).

3 Likes

I see what you’re saying. I shouldn’t have used “I recommend”, “it is recommended” would have been better. But getting rid of “you” would have made things bulky in my opinion - maybe you can give me pointers on fixing that? At any rate, thank you for the feedback, and I’ll try to incorporate it into future guides!

2 Likes

You don’t have to get rid of ‘you’, you can just reduce the frequency with which you use it.

Or…

Getting rid of the word ‘you’ isn’t required, one can just reduce the number of times it is used.

The goal being twofold… You reduce the repetition and make it easier to follow. The word was used ~120 times in your article.

2 Likes

Wow. Just… wow. OK, yeah, I should tone that down a bit.

1 Like

Another is ‘never start a sentence with the same word more than twice in a row.’ Our eyes skip around as we read - we don’t actually read (in our heads) in a linear fashion. So, things like this aid in readability.

The way our brains work is pretty fascinating.

The best trick I’ve ever learned - and it’s a good one - is to read it ALOUD before publishing. Don’t just read it in your head, read it aloud. As in sit there and read it word for word.

Then, there’s the matter of subheading distribution and too much passive voice. A good indicator for readability is the Flesche method.

4 Likes