RuneAudio Forum

Over the last few months we almost completely focused ourselves in the development of the deeply reworked 0.3-alpha. Something we had to neglect during this time has been the official Documentation page, which starts now to feel out of date and incomplete.

I was thinking about involving a sort of collaborative writing, opening it to user's contributions. I'm taking into consideration some solutions, in particular some based on GitHub (managing the docs through our repository seems a good idea to me). Suggestions are welcome on this front.

In the meanwhile, if there are some volunteers to extend the current informations or review them (my English grammar is far from being perfect ), they are truly welcome

My proposal:

1 Quick start guide
1.1 Download and extract
1.2 Prepare the SD card
1.3 Prepare the device
1.4 First use
1.4.1 Use an USB stick
1.4.2 Use the new features of 0.3 (radio ecc)
1.4.3 Use the NAS system
2 Player setup
2.1 The web interface – RuneUI
2.2 Accessing the RuneUI with SSH
2.3 Database configuration
3 Advanced users
4 More help

ACX wrote:I was thinking about involving a sort of collaborative writing, opening it to user's contributions. I'm taking into consideration some solutions, in particular some based on GitHub (managing the docs through our repository seems a good idea to me). Suggestions are welcome on this front.

Hi ACX,
I'll try to help out when I can find the time to do so. My suggestion is to use a wiki for the documentation, as it is a tried and true way of collaborative writing.

ACX wrote:I was thinking about involving a sort of collaborative writing, opening it to user's contributions. I'm taking into consideration some solutions, in particular some based on GitHub (managing the docs through our repository seems a good idea to me). Suggestions are welcome on this front.

Hi ACX,
I'll try to help out when I can find the time to do so. My suggestion is to use a wiki for the documentation, as it is an already established way of collaborative writing.

skrodahl wrote:My suggestion is to use a wiki for the documentation, as it is an already established way of collaborative writing.

Hi skrodahl,
I'm not a big fan of wikis, they always tend to be overcomplicated and disordered at the end (the old MPD's wiki is a clear example of that, a true mess...). I'd prefer to keep it inside WordPress but managed through GitHub if possible.

When you all figure out how you want to do this, I can try and help out as well. Considering I work from home most of the time, I am almost always online.

Hi everyone,
I finally took a decision about this.

The choosen platform for the collaborative documentation is... GitHub (surprise, uh?).
https://github.com/RuneAudio/Docs

The documentation is written in Markdown syntax (the same used by GitHub, although it uses a slightly different flavored version) and built with MkDocs, a wonderful tool that automatically builds a static site from documentation source files. I preferred MkDocs to more mature tools like Sphinx because it is fast and simple, and gives me absolute control on the template.

Here you can see the result (already published online):
http://www.runeaudio.com/documentation/
I already set up the content structure, now it's your turn to contribute to this
Don't hesitate to ask me questions about how to contribute and to suggest further improvements.

I started playing with this some tonight, and it looks pretty straightforward. It might help, just for flow, for folks to mention what subject they plan on focusing on in their writing. Not that we can't kibbitz amongst us, but if someone has particular strength/understanding in a specific area, it could help us from pig-piling one subject. I took a stab at 'Flashing an SD card in Windows' because I've done it before, and it was a quick easy exercise in GitHub and StackEdit. (Easier stuff than I expected.) Also, feel free to tear apart what I've drawn up; immediately after I published it I realized a couple things that need adding. You good folks will see much more.

Thanks!
-Fishstix

Fishstix wrote:I took a stab at 'Flashing an SD card in Windows' because I've done it before, and it was a quick easy exercise in GitHub and StackEdit. (Easier stuff than I expected.) Also, feel free to tear apart what I've drawn up; immediately after I published it I realized a couple things that need adding. You good folks will see much more.

Good beginning Fishstix! I already suggested you some modifications before the pull merge.

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....