Handbook style

[jamesmills]

This issue was extracted from another issue: #9 (comment)

What do you all think about the package/site used by the frontend group? http://frontend.clicksco.com/standards/index.php/Introduction - @jonspark

I like the format and the system the FE guys have used. I do feel it overcomplicates things slightly.

Reasons I picked GitHub Pages:

• They have a lot of example code to include in their documents and we don't.
• It was easy to get up and running.
• It allows us to host the static pages free, easily and quickly.
• It was a great way to get started to allow every member of the team access to contribute to the handbook so it did not feel like I was trying to dictate.
• It's going to be easy to maintain when everyones time is tight.

I am happy to open this up for discussion. I would like to hear your thoughts on moving it to a different system, just to use Markdown is not a good enough answer, lol ;-)

[ampersarnie]

I think the main reason for the FE guys to use Daux was that it was easily available and didn't require much intervention in terms of markup. It was just as easy as adding/editing a markdown file and they had a page generated from that. I can't remember the exact discussion or can find an issue where it might have been discussed - having one of those days - but I'm positive that was it.

To be fair, I don't mind either way, as long as it is easy to add/edit content and is presented nicely. But I think the usage of Markdown is a good reason because of the ease it will allow, preventing any bother with HTML markup. Some of the reasons you stated for the choice of GitHub Pages can easily be applied to a system like Daux (aside from hosting?). At the end of the day, it is just going to be a matter of what everyone is comfortable with.

As for example code, now that it has been mentioned, is there going to be a point where we will start implementing examples into the Docs? Maybe a separate issue needed to discuss this possibility?

[jonspark]

The main benefit I see of Markdown, and it's why I use it day-to-day, is that it can be converted and used like code.

I don't use Word, using MD, I can output my doc to a PDF and, if I need to, I could also output it to HTML. In this case, it would probably be the other way around... output to HTML, PDF if required.