search

uboslinux / ubos-website

The UBOS website including docs
https://ubos.net/
3 stars 1 forks source link

Reduce redundancies in the documentation #6

Open jernst opened 8 years ago

jernst commented 8 years ago

Identify which sections can be merged, and do so, because they essentially talk about the same thing.

eaguirre1 commented 7 years ago

Hi, I would like to help on this. What can I do?

jernst commented 7 years ago

@eaguirre1 : Welcome!

I suggest you read through the on-line docs at http://ubos.net/docs/ and make notes which pages / sections within pages seem to overlap. You can be as throrough (or not) as you like -- better getting rid of some redundancies than none!

Then, if you know how to use git and know how to install Sphinx and Jekyll, clone https://github.com/uboslinux/ubos-docs, make the changes you want to make, say "make" as described here, and when you like the results, commit and create a pull request.

eaguirre1 commented 7 years ago

Sorry for the delayed response. I have been deep on other projects. Thanks for the tips. I will continue to gradually work on the docs.

jamesjwong commented 7 years ago

Hi @jernst,

My name is Jimmy, and I'm a post-bacc CS student currently enrolled in an intro FOSS course. One of our assignments is to make a couple of contributions to an open source project, and I happened across this one! I think UBOS is an awesome idea.

I think my background in English Lit. and Law can help with regards to documentation. Preliminarily, I'm a little unclear on what a "redundancy" is (and if they have already been identified and fixed). To make sure I have a good idea of how I can help with redundancies and documentation, here are a few issues I found on the "How to Use UBOS" part of documentation.

  1. Overlapping topics/themes of Troubleshooting and User FAQ I think a clear example of this is "I need help" v. "Help! I have trouble!". When reviewing this part, I think thematically this section could be merged because a question like "What should I do if I get an error..." also makes sense to be under the "Troubleshooting" header.

  2. Sub-headings for Installation Under "Installation" almost all the sub-headings start with "Run UBOS on..." I think we could clear this up maybe be just starting with the compatible device (e.g., "Raspberry Pi Zero or 1").

  3. Location of "Migrating from one app to another" This isn't exactly a redundancy issue, but I think this topic could be moved up more to logically fit closer with "Managing sites and apps".

Let me know if these suggestions are on the right track. If so (and you think I can help on the project), I'll look into committing and creating a pull request (I know how to use git).

jernst commented 7 years ago

Hey @jamesjwong , all useful contributions are gladly accepted. You are on the right track with your findings ... in addition, there are more fundamental redundancies in terms of where we talk about what. I'm sure if you dig into it, you will find them.

P.S. If you are a CS student, I would certainly encourage you to make more fundamental contributions. On the easy side, something like "why does Tor not come up in time on the Raspberry Pi 1 but all other platforms" (see current release notes). On the hard and impressive side: "how could I modify UBOS infrastructure -- but not app packages -- to run (some) apps in Linux containers." I'm fairly certain the latter can be done, but it would be great if somebody could demonstrate that. (P.S. as a hiring manager, I'd be rather impressed by that one)

eaguirre1 commented 7 years ago

Besides on what was mentioned above, I believe I have found:

  1. On how to develop UBOS: The "Continuing the Arch Linux installation on a PC or VirtualBox virtual machine" and "Finishing the Arch development installation by adding UBOS tools" can be merged into one section on Arch Development installation.

Not sure if there is more. The documentation is very dummy proof which is great so you will never lose where you are and can virtually get to anywhere from the same page. Let me know I am on the right track.

eaguirre1 commented 7 years ago

Also, how do you manage to use the software to make changes to what you already have on the website?

jernst commented 7 years ago

Those two sections are intentionally separate because the second one also applies to other installation methods (like on ARM).

To get changes on the site, you submit a pull request, if approved, it gets merged and I then publish it to the site.