diff --git a/docs/docs/FAQ.md b/docs/docs/FAQ.md new file mode 100644 index 0000000..9c4d13f --- /dev/null +++ b/docs/docs/FAQ.md @@ -0,0 +1,28 @@ +# FAQ + +## Why? + +Because I like to code my way around problems. See [Here](why.md) for a better explanation + +## Why the command line? + +Simple answer, I don't like writing GUI's. Also typing a few commands +seems much more efficient than lots of clicking too. + +There is no reason there cant be one, feel free to submit a pull +request. + +## Why Markdown, and not + +A few reasons. + + 1. I teach in computing, and encourage the students to use GitHub, + which will render Markdown nicely in the web interface. It + seemed like a good idea to reinforce this good practice. + 1. Its got a nice clean syntax, and as text can be edited on just about anything. + 1. It has support for things like Maths, and Code. + +## Pink Lady Mode? + +I Like Puns, I Like obscure movie references, (I don't particularly +like the movie). And it seemed to fit. diff --git a/docs/docs/gettingstarted.md b/docs/docs/gettingstarted.md new file mode 100644 index 0000000..e7340bb --- /dev/null +++ b/docs/docs/gettingstarted.md @@ -0,0 +1,14 @@ +# Getting Started + +## Requirements + +## Installing + + +## Building our Template Document + +## Modifying our Template + + + + diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..f2b829d --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,40 @@ +# Markdown Marking + +This project allows us to generate documents such as Coursework +Briefs, or Feedback using markdown. I find it a much nicer way of +working, and the generated docs should be more consistent for the +students. +You can read my rationale for developing it [here](why) + + + + + + + + +# Improvements + +## Bugs or Undocumented Features? + +Are to be expected, been cobbling this together in my weekends. + +There is an [Issue tracker](https://github.coventry.ac.uk/aa9863/MarkdownMark/issues) +please use it. + + +## Contributing + +If you have any: + + - Ideas for improvement / Feature Requests + - New Templates + - Code contributions + +You are welcome to contribute to the project. The more people who use +it the better. + +Either get in touch, submit and issue, or a pull request with your changes. + + + diff --git a/docs/docs/why.md b/docs/docs/why.md new file mode 100644 index 0000000..1af4427 --- /dev/null +++ b/docs/docs/why.md @@ -0,0 +1,74 @@ +# Why write this + +> NOTE: A lot of this is my own opinion (and may verge on a rant at +> time). +> +> The "science" behind things like working efficiently can be +> difficult. What works for one person, may not work for another. +> Equally, things that drive one person mad, is the perfect way of +> working for another. As a veteran of the Emacs VS Vi "Holy War", +> used to seeing two completely different philosophies on how to do +> the same thing. + +Currently in Note form. I will come back and fix when I have time. + + +## (My View on) The problem with our current templates + + - Quite simply, Word is an Abomination when it comes to this. + - Its good for writing text + - But formatting has never been its strong point + - This is even worse when we try to use to create standardised forms + - Usual approach is to layout with tables. + - Creates a doc that looks great, until you come to actually use it + - Different version of word have slightly different rendering + - Copy and Paste is a PITA + - Lets not even go into using it on Linux + - Even worse is the built in forms thing, because not even the creator of it has managed to use it correctly. + - We also have Excel + - Really hammers home this problem. + - All the thought goes into making it look pretty, but not into the people who actually have to use it. + - Knuth (and others) have seen this, so we separate the content creation from the actually formatting. + - Let me get on with writing the content + - Let someone else work out the template. + - The Experts in each field do their job, rather than fighting with one and other. + +## Why use HTML + + - Actually, its pretty good at content. Almost certainly more HTML docs than anything else. + - Hate the Modern argument, but its true. + - If the Uni wants to move to this mobile first focus (We wont even go there) then supporting it via the web is a good idea. + - End up with templates that look as good on the phone, as they do the screen and in print. + - Can also follow DRY. Templates gives us much more control of this. + - Lets say uni suddenly decides that everything is in comic sans. (Its such a friendly font) + - Simple as changing one style sheet, that cascades to all docs. Better still, this can be retrospective. + - Unless printed. + - But I Have to learn HTML + - Turns out its not that difficult. They teach it to school kids. + - Also we are not doing any of the "Magic" in web 2.0. No JavaScript or stuff like that. Just pure HTML5. + - We can also use Online layout generators. + + - There are some downsides: + - May have issues in different browsers. (But as we are using pure HTML5, it shouldn't be a problem) + - Needs to be online: Meh, its the way the uni is going anyway. Or just print the thing. (and I am working on PDF conversion) + + +## Why use Markdown + + - In the Beginning there was Latex, and it was good + - But you needed to be a geek + - Shit like Lyx came along, which (IMHO) had all the downsides of BOTH latex, and Word. + - In the past it would have been Org, but that tends to have the Emacs Barrier + - Instead I tend to use MD, (and persuade the students to use it) + - Is probably the simplest markup language there is + - But It Supports things like CODE, and MATHS!! + - Its a fecking great idea + - Its powerful. I use it for Lecture notes ,slides, lab sheets. + - I have had students write Dissertations in it + - Its a Darn Sight Easier than Latex + - + + + - In the future I would like to add support for: + - Org + - ReST diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..296c0b9 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1 @@ +site_name: Markdown Mark