Overhaul/improve documentation

[petr-tik]

• Use markdown features for headings, sub-headings and levels
• Add section for Gruel
• Rearrange items according to required knowledge - Engine first, Spin, Orb, Cog
• Add usage examples

You want documentation to read as a tutorial. Thinking about usage examples will help you think about APIs from design and user perspectives at the same time.

Happy to discuss and then help with this.

[cratuki]

I reckon we should create this tutorial under the 'scenarios' directory. I am open to changing the name of that to 'tutorial'.

There are usage-examples in there, and it is ordered to build knowledge up gradually.

The required-knowledge stuff is currently started in docs/glossary. This should probably go into this tutorial area.

Further thoughts,

• The tutorials files must be launch-able. Otherwise it is hard to test that they are correct.
• Some people prefer to follow web documentation. We probably need a website, and ability to render the tutorial to a web format.

It would be a fair bit of work to refactor Gruel. It is not in a working state at the moment, and I no longer have faith in the test-driven techniques that I used to develop it. It may need to come out of the tree.

[cratuki]

Further thought about the tutorial style. This morning I have been messing around with some sample code to make a DNS request. I thought - this is something that is potentially interesting to someone learning the platform. We could grow the tutorial by taking parts of TCP/IP Illustrated, and then showing how to (and how easy it is to) implement items in Solent.

[cratuki]

This resource will be useful,
http://python.apichecklist.com/
https://news.ycombinator.com/item?id=15827945

[cratuki]

While doing the tutorials work, keep issue #75 in mind. It should be easy to create that behaviour when my state-of-mind is looking at the tutorial series on network-programming.

[cratuki]

Depends on issue #107. I am expecting a follow-up issue from there that where I will commoditise the engine event loop so that we can have side-by-side select(2), poll(2), epoll(7) and iocp implementations of the event loop. It would be do documentation as the last-stage of that process. This would act as a form of testing against the work-just-completed.

[cratuki]

Candidate documentation structure,

• Introduction

• Project Overview

• Tutorial

• Concepts

• FAQ

:: Introduction

Explain that the manual is structured to introduce concepts before it refers to them. But encourage people to read out-of-order. For example, if they had a particular interest in building a network client, crawl through the tutorial until you see something that makes sense. Get it working. Then use the concepts document to construct it.

Explain that the Concepts section is the heart of the manual. It is probably dry to attempt to read from start to finish. But as you become more familiar with the manual, this is where you will spend your time.

:: Project Overview

You can give intent and background in here.

:: Tutorial

This should gradually build up

:: Concepts

These are the man pages of this system. It should be alphabetically ordered.

Concepts should be written to a clear structure.

• Quick (checklist summary of the what/why/when/how sections)

• Overview ('what'. may include a super-quick example)

• Background (why it exists, what problem it solves)

• In Your Toolbox (When to use it: paragraph)

• Use (This is descriptive, as in 'How to use it')

• Resources (Links to resources that give more context. In particular, tutorial sections)

:: FAQ

This should have a technology emphasis. Think of it as "Techniques and Troubleshooting". Non-technical stuff should just be pointers into Project Overview.