edit index.md, basic structure for articles

articles/ImageSharp/GettingStarted.md

@@ -1,8 +1,11 @@
 # Getting started with ImageSharp
 So you've gone and added the ImageSharp packages and you've been left with the question "so what to I do now?" hopefully some of these snippets can answer that question for you, or at least get you started.
 
-## How do I open a jpg scale it by half and save it again as a jpg?
-This is our standard go to sample.
+## Scaling a jpeg by half and save it again as a jpg
+In this very basic example you are actually utilizing a bunch of ImageSharp features:
+- [Pixel Formats](PixelFormats.md) by using `Rgba32`
+- [Image Formats](ImageFormats.md) by loading and saving a jpeg image
+- [Image Processors](Processing.md) by calling `Mutate()` and `Resize()`
 
 ```c#
 using (Image<Rgba32> image = Image.Load("foo.jpg")) //open the file and detect the file type and decode it
@@ -22,3 +25,6 @@ using(Image<Rgba32> image = new Image<Rgba32>(width, height)) // creates a new i
  // do your drawing in here...
 } // dispose - releasing memory into a memory pool ready for the next image you wish to process
 ```
+
+## Why is [](xref:SixLabors.ImageSharp.Image`1?displayProperty=name) a generic class?
+Check out the [Pixel Formats](PixelFormats.md) article for the answer!

articles/ImageSharp/ImageFormats.md

@@ -0,0 +1 @@
+TODO

articles/ImageSharp/PixelFormats.md

@@ -0,0 +1,23 @@
+# Pixel Formats
+
+## Why is [](xref:SixLabors.ImageSharp.Image`1?displayProperty=name) a generic class?
+
+We are supporting multiple pixel formats just like `System.Drawing` does. However, unlike their closed [PixelFormat](https://docs.microsoft.com/en-us/dotnet/api/system.drawing.imaging.pixelformat) enumeration, our solution is extensible.
+A pixel is basically a small value type object (struct), describing the color value at a given point. An image is essentially a **generic** 2D array of pixels stored in a contigous memory block.
+
+### Ok, how do I create an image with a pixel type other, than `Rgba32`?
+
+Have a look at the various pixel types available under [](xref:SixLabors.ImageSharp.PixelFormats#structs)! After picking the pixel type of your choice, use it as a generic argument for [](xref:SixLabors.ImageSharp.Image`1?displayProperty=name), eg. by instantiating `Image<Bgr24>`.
+
+### Can I define my own pixel type?
+
+Yes, you just need to define a struct implementing [](xref:SixLabors.ImageSharp.PixelFormats.IPixel`1) and use it as a generic argument for [](xref:SixLabors.ImageSharp.Image`1?displayProperty=name).
+
+### I have a monochrome image and I want to store it in a compact way. Can I store a pixel on a single bit?
+
+No. Our architecture does not allow sub-byte pixel types at the moment. This feature is incredibly complex to implement, and you are going to pay the price of the low memory footprint in processing speed / CPU load.
+
+### Can I decode into formats like [CMYK](https://en.wikipedia.org/wiki/CMYK_color_model) or [CIELAB](https://en.wikipedia.org/wiki/Lab_color_space)?
+
+Unfortunately it's not possible at the moment.
+

articles/intro.md

@@ -1 +1,4 @@
-# Add your introductions here!
+# Introduction
+This is a FAQ-style guide for our API. We tried to provide short answers for the most common questions concerning our libraries.
+Can't find what you're looking for? Have a try by [exploring our API](api/index.md). If you still don't find what you're looking for, feel free to ping us on our [gitter channel](https://gitter.im/ImageSharp/General).
+Please **do not** open GitHub issues for questions.

articles/toc.md

@@ -0,0 +1,12 @@
+# [Introduction](intro.md)
+# [ImageSharp](ImageSharp/GettingStarted.md)
+## [Pixel Formats](ImageSharp/PixelFormats.md)
+## [Image Formats](ImageSharp/ImageFormats.md)
+## [Processing images](ImageSharp/Processing.md)
+## [Drawing]()
+## [Configuration]()
+## [Memory Management]()
+## [Additonal topics]()
+### [Loading raw pixel data]()
+### [Saving raw pixel data]()
+### [Efficient pixel manipulation]()

articles/toc.yml

@@ -1,5 +0,0 @@
-- name: Introduction
-  href: intro.md
-
-- name: ImageSharp
-  href: ImageSharp/GettingStarted.md

index.md

@@ -1,4 +1,37 @@
 # Welcome to Six Labors documentation!
 
-You can find tutorials, examples and API details covings all of Six Labors projects. This includes SixLabors.ImageSharp, SixLabors.ImageSharp.Web, SixLabors.Shape and SixLabors.Fonts.
+You can find tutorials, examples and API details covering all Six Labors projects.
 
+### [Articles](articles/intro.md)
+Examples and explanatory documentation about our API.
+
+### [API documentation](api/index.md)
+Detailed documentation for the entire API available across our projects.
+
+# SixLabors Projects
+Our graphics libraries are split into different projects. They cover different concerns separately, but there is strong cohesion.
+
+### [SixLabors.Core](https://github.com/SixLabors/Core)
+Common classes and structs used aross our projects including [](xref:SixLabors.Primitives)
+
+### [SixLabors.ImageSharp](https://github.com/SixLabors/ImageSharp)
+- Contains the generic [](xref:SixLabirs.Image`1?displayProperty=name) class, PixelFormats, Configuration, and other core functionality.
+- The [](xref:SixLabors.ImageSharp.Formats.IImageFormat?displayProperty=name) interface, Jpeg, Png, Bmp, and Gif formats.
+- The image processor infrastructure, `.Mutate()` and `.Clone()`
+  - Transform methods like Resize, Crop, Skew, Rotate - Anything that alters the dimensions of the image.
+  - Non-transform methods like Gaussian Blur, Pixelate, Edge Detection - Anything that maintains the original image dimensions.
+
+### [SixLabors.Shapes](https://github.com/SixLabors/Shapes)
+Net standard geometry/shape manipulation library, can be used to instantiate various shapes allowing operations like merge, split, intersections etc.
+The SixLabors.Drawing library is based on Shapes.
+
+### [SixLabors.Fonts](https://github.com/SixLabors/Fonts)
+Font loading and drawing library. Text drawing in `SixLabors.ImageSharp.Drawing` is based on this library.
+
+### SixLabors.ImageSharp.Drawing
+- Brushes and various drawing algorithms, including drawing images.
+- Various vector drawing methods for drawing paths, polygons etc.
+- Text drawing (based on [SixLabors.Fonts](https://github.com/SixLabors/Fonts))
+
+### [SixLabors.ImageSharp.Web](https://github.com/SixLabors/ImageSharp.Web)
+ASP.NET-Core middleware for image manipulation.