Improve the docs

Help wanted! How to contribute to RuneAudio project

Re: Improve the docs

Postby ACX » 22 Oct 2014, 02:20

cmh714 wrote:I can create content but dont have any cycles to learn anything new. I can easily do the flash for Mac section, just let me know if a Word doc or something like that would work for someone to convert for the site....

Markdown is VERY simple to use. For the lazy ones there are also some WYSIWYG editors around like StackEdit.
User avatar
ACX
RuneAudio co-founder
 
Posts: 1680
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

Re: Improve the docs

Postby Fishstix » 22 Oct 2014, 02:31

Hey cmh,

I totally understand; I know *nothing* about coding. Check out Stack Edit https://stackedit.io/, it's actually very similar to this forum layout in terms of ease; it's basically a text editor that outputs to simple code. But if you still want to just write in .doc format or whatever is easy (again, *totally* understand) you could shoot me what you've written in a PM, I'll cut and paste and format it. I don't know a thing about Macs, except that they are super pretty. So your contribution would be *very* helpful.

Try checking out this link at GitHub; https://github.com/Fishstixx/Docs/blob/patch-1/docs/quick-start/sd-card-setup-windows.md It's my writeup on flashing in Windows. I think it's supposed to be public, let me know if it isn't, and I'll shoot you a simple text of it. This was the format that made sense to me, let me know if we're missing something. I got some good feedback already about this, and I have a little to change.

Firstly, for now we'll be doing separate and complete rundowns on SD flashing per each OS. If you want to grab what I've written, cut and paste and mod for Mac, you are welcome to. Or if you want to write from scratch, your writing style (and what i've missed) will help me go back and refine what I've done/will do. Either way, I would appreciate feedback if I've missed anything in my section.

Secondly, the 'common issues' will be moved off to the troubleshooting section.

Other than that, formatting things and I'll take care of those.

ACX linked us to http://elinux.org/RPi_Easy_SD_Card_Setup#Flashing_the_SD_card_using_Mac_OSX for 'inspiration.' It helped me from leaving important things out.

Cheers!
Fishstix
Fishstix
 
Posts: 22
Joined: 22 Sep 2014, 22:13

Re: Improve the docs

Postby cmh714 » 22 Oct 2014, 02:48

thanks for offering to assist Fishstix. I saw the link ACX provided, and I use ApplePi Baker so can easily work on that over the next day or so...in addition to the 50 things I need to do for my new job :)

Yes the Mac is pretty, I also have a Windows laptop for work and many VM's on the Mac for whatever I am playing with :)
cmh714
 
Posts: 357
Joined: 04 May 2014, 03:06

Re: Improve the docs

Postby ACX » 22 Oct 2014, 23:55

I added a "edit this page on GitHub" link on every page to make things even easier, you can see a working example here:
http://www.runeaudio.com/documentation/ ... setup-mac/
User avatar
ACX
RuneAudio co-founder
 
Posts: 1680
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

Re: Improve the docs

Postby cmh714 » 23 Oct 2014, 15:34

I will take a look, and yes it does appear that Stackedit looks pretty easy. Now to find some time :)
cmh714
 
Posts: 357
Joined: 04 May 2014, 03:06

Re: Improve the docs

Postby cmh714 » 03 Nov 2014, 23:21

So I too my first crack at doing this in git using Fishstix doc as my template.....I think its ok, but I couldnt figure out yet getting a screenshot up there....any help is appreciated, or I could send the screenshot along to someone to get in there.......or how to merge it or anything else as I am not a git user normally

let me know what I did wrong or right and I can try to correct it going forward :)
cmh714
 
Posts: 357
Joined: 04 May 2014, 03:06

Re: Improve the docs

Postby Fishstix » 04 Nov 2014, 20:10

Hey cmh714,

It took me a while to wrap my head around some of the tricks of StackEdit, ACX has been really nice about showing me ways to improve and normalize what I've done.

Are you asking about inline images for your doc? Or an output of what you've accomplished so far for double checking? The former I accomplished by linking with my gmail account. Feels like a little bit of a workaround, but when I upload them to GitHub, the public images I have on gmail still have viable links that carry over. So it ended up being a great time saver.

If it's the latter, your GitHub forked page should be public, though I can't find it from where I'm at. A link from here to there should be just fine, and we can check it out from there.

If you are having trouble getting your StackEdit doc *into* GitHub, well, we can learn this together. I feel pretty clumsy with it myself. From what I understand (still learning the terminology) ACX or one of the core dev team would be doing the actual *merging,* which is where your work get's officially put into the documents. The beauty of GitHub is that you or anyone can 'fork' a copy of anything (the tiny tiny pencil icon,) update the doc as you like (which is where the copy and paste from your StackEdit would happen) and when you are happy with it, at the bottom of the screen you give it a new file name(e.g. mac_flash_rewrite#1.md), a short description of what you've changed and why, and click 'propose file change.' Which makes it available to the core team to review. After a couple back and forth emails to tighten things up, it gets 'merged' (meaning accepted) back into the source files and updated to the RuneAudio site. Which is not to say that it's written in stone at that point; it can always be forked and improved/updated and remerged.

I am sorry if some or all of this is reductive, useless or off the mark. I've been away a few days and am just trying to get back into the swing of things, catch up on the forums. I've got some Rune writing to do myself. If you have questions, I'll be around and get back to you quickly. I could probably put up some screenshots for the how-to if that helps. Thanks for taking the time to write, cmh!

All the Best,
-Fishstix
Fishstix
 
Posts: 22
Joined: 22 Sep 2014, 22:13

Re: Improve the docs

Postby ACX » 02 Dec 2014, 15:22

Some useful resources for this task - a collection of free online Markdown editors:
http://sixrevisions.com/tools/online-markdown-editors/
User avatar
ACX
RuneAudio co-founder
 
Posts: 1680
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

Re: Improve the docs

Postby ACX » 03 Feb 2015, 18:02

Just updated the Mac first setup instructions:
http://www.runeaudio.com/documentation/ ... setup-mac/
Thanks to apassemard for his pull request!

And also a big thank you to everyone else who already contributed to the Docs up to now (Fishstixx, kdubious, pawelad, etc).
User avatar
ACX
RuneAudio co-founder
 
Posts: 1680
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

support RuneAudio Donate with PayPal

Previous

Return to Help the project

Who is online

Users browsing this forum: No registered users and 1 guest