How do we write it?

[shoter]

Writing a book is a complicated thing. First problem is to choose technology in which this book will be written. The simple one is markdown but is it the most suitable one?

Markdown is simple language which is very easy to use and create simple documents formatted using not so much constructs. It is also easy to display it on the GitHub website.

There is also other technology which I know and is widely used by universities etc. to publish books and articles about new science discoveries. It is LaTeX. It's compilable language that's using not simple (but not hard) language to describe structure and content of the document. It is compilable by default to PDF . It allows to do literally everything with the document.

Everyone probably knows how markdown works but I will summarize pros and cons of LaTeX:

Pros:

• It has wide variety of options to customize how document is being displayed with many templates on the internet.
• It feels more like programming when you are dealing with this language.
• Everything looks neat on PDF or on paper.
• Possibility of defining macros, conditional compilation and more.
• Automatically generates Table of Contents, Table of most important words, Table of used Images and other tables.
• You can divide document into multiple files.

Cons:

• It's a lot harder compared to MarkDown
• It has a lot of weird (at first) behaviours. Sometimes it can take some time to resolve some issue with formatting.
• You need to compile document before you see changes. When I was dealing with 70 page long document it took me ~20 seconds to compile.
• You need to compile 3 times the same document to see changes ( :D ).

Personally I would pick up LaTeX. It is very frustrating to read documents made in Markdown. They look just ugly. You are reading them and everything is fine but the layout is terrible. I always have the weird feeling when reading long documents in markdown.

But there is probably much wider variety of technologies that can be used to write this book. What would you choose and why?

[patrickklaeren]

For the prosperity of the fact many people don't bother to read a lot, and I'd like to think we're trying to keep this as simple as possible to host on Github where we can direct users from the guild. I'd also like to encourage as much collaboration as possible and therefore markdown seems like the logical choice to me.

[JohanLarsson]

I think markdown is good to start with if nothing else.
Somewhat related is if we should use animated gifs. A gif can be very nice for explaining for example how to set a breakpoint and inspect things in the debugger.

[Trinitek]

Also, with Markdown, we will be able to utilize static site builders like MkDocs if we want to in the future.

I agree that GIFs would be useful to demonstrate how to use the debugger.