Improve the docs

Help wanted! How to contribute to RuneAudio project

Improve the docs

Postby ACX » 24 Jul 2014, 01:04

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 :)
User avatar
ACX
RuneAudio co-founder
 
Posts: 1692
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

Re: Improve the docs

Postby Mte90 » 05 Aug 2014, 17:13

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
Professional #Geek, #Developer, #Debian user, #FirefoxOS Training Lead Italy, #KDE/#QT lover, Zagoriano, Moderator of #Wordpress Italy Plus
Mte90
 
Posts: 16
Joined: 04 May 2014, 11:26

Re: Improve the docs

Postby skrodahl » 06 Aug 2014, 07:33

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

Muffsy Phono Preamp PP-3 || Audiobah TPA3116 || ESP P88 || ProJect Debut Carbon Espirit DC || RuneAudio / RaspBerry Pi / HifiBerry DAC || Dynaco A25
User avatar
skrodahl
Moderator
 
Posts: 160
Joined: 27 Jan 2014, 10:08
Location: Sweden

Re: Improve the docs

Postby skrodahl » 06 Aug 2014, 07:34

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

Muffsy Phono Preamp PP-3 || Audiobah TPA3116 || ESP P88 || ProJect Debut Carbon Espirit DC || RuneAudio / RaspBerry Pi / HifiBerry DAC || Dynaco A25
User avatar
skrodahl
Moderator
 
Posts: 160
Joined: 27 Jan 2014, 10:08
Location: Sweden

Re: R: Improve the docs

Postby ACX » 06 Aug 2014, 12:28

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.
User avatar
ACX
RuneAudio co-founder
 
Posts: 1692
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

Re: Improve the docs

Postby cmh714 » 07 Aug 2014, 16:49

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.
cmh714
 
Posts: 470
Joined: 04 May 2014, 03:06

Re: Improve the docs

Postby ACX » 21 Oct 2014, 01:33

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.
User avatar
ACX
RuneAudio co-founder
 
Posts: 1692
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

Re: Improve the docs

Postby Fishstix » 21 Oct 2014, 08:23

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
 
Posts: 22
Joined: 22 Sep 2014, 22:13

Re: Improve the docs

Postby ACX » 21 Oct 2014, 11:46

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.
User avatar
ACX
RuneAudio co-founder
 
Posts: 1692
Joined: 29 Nov 2013, 02:25
Location: Udine, Italy

Re: Improve the docs

Postby cmh714 » 22 Oct 2014, 01:56

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....
cmh714
 
Posts: 470
Joined: 04 May 2014, 03:06

support RuneAudio Donate with PayPal

Next

Return to Help the project

Who is online

Users browsing this forum: No registered users and 0 guests