Create developer-friendly documentation with examples

[antonfirsov]

The Problem

I strongly believe that - in order to improve our adoption rates - a well structured sample-based documentation is at least as important as an auto-generated API documentation (#402). It would also save us significant amount of time, because most of the questions could be answered using a link to a paragraph.

I want to do most of this job for the 1.0 release, but I need your help in form of reviews + suggestions!

The Solution

My vision is to have a FAQ-style documentation covering our main features with basic examples. It should focus mostly on answering the "How can I achieve my XYZ thing?" questions we get on gitter + cover some of the "Why am I experiencing XYZ thing?" ones.

Topics

Contributors: Please feel free to edit this list!
Everyone else: Leave your suggestions in comments!

Basics

• ImageSharp packages
• Pixel formats
• Opening/Saving
• Creating an empty image
• Basic resize
• ColorBuilder<TPixel>
• "Drawing" a pixel using indexers (+ explain why don't we use the Drawing API for drawing a single pixel)a

Encoders

• Jpeg (Parameters: Quality, JpegSubsample)
• Png (Parameters: PngColorType, PaletteSize)
• Gif
• Bmp

Remember:

• To communicate the defaults!
• Most users end up having the question "How to reduce size?" vs "How to improve quality?". We should provide answers for each format!

Additional topics:

• How do I perform a resize operation and save it as its original format to a stream?

Processors

Advanced resize

• Resamplers
• Issues with aspect ratio ("bars")

Transformations (Link matching CSS features, if possible!)

• Affine
• Projective
• Color transforms

Other

• Blend modes
• BackgroundColor()
• AutoOrient() (see Image width and image height are getting mixed up #790, very frequent question!)

Drawing

• Fill, draw, Brushes, Pens
• Basic shapes: rectangle, circle
• Path
• Image
• Text

Working with Frames and Gifs

• Creating, cloning, exporting etc.
• Frame delay (in ImageFrameMetaData)

Working with raw pixel data

• All kind of span stuff
• Interop: Marshalling pixel data pointers (eg. to OpenTK)
• Interop: S.D: basic example, matching PixelFormat with IPixel implementations

Configuration

• Controlling parallelism
• Using different Configuration-s in a process (+probably a demo with DI integration)

Memory issues

• Ensuring 64 bits :P
• Explaining pool behavior + why are we pooling
• Overriding default behavior (after implementing Implement pluggable memory management #225)

Ideas for Additional examples

• Creating an image strip

[JimBobSquarePants]

@antonfirsov Top notch suggestions; I completely agree.

I know how to setup the docfx stuff (except git submodules but I can read up on that)

I want to refactor the namespaces for the API docs but work on other docs can start as soon as anyone has an opportunity.

[asterixorobelix]

@antonfirsov @JimBobSquarePants

It has begun: https://github.com/SixLabors/ImageSharp/wiki/Questions-and-Answers

[JimBobSquarePants]

Hi @asterixorobelix

Thanks for taking the effort and time to add that page but we do not intend to use the wiki pages for documentation. Rather we plan to use docfx as described in #402 to host both Q&A style documentation as well as API documentation.

This allows us to maintain a single location for our documentation for both cases which makes our work a lot easier to do.

[binn]

Please do, documentation is life.

[ambroselittle]

As a n00b to ImageSharp (and long-time commercial API guy), I can definitely say having even some basic docs goes a very long way. Prioritize: 1) a samples collection of the most common tasks, 2) good API docs.

Am I right that I currently need to browse the code to figure things out, or am I missing some docs somewhere?

[antonfirsov]

@ambroselittle we have a few sample projects in a separate repository, but yeah that's not well visible.

[ambroselittle]

After inspection, it turns out my use case appears to be the default (for resize), so yay for good defaults! Thanks. 🎉

[antonfirsov]

note to self, but might be interesting to others until the information is actually available in our docs

My gitter comment explaining difference between System.Drawing.Imaging.PixelFormat and our pixel types.

Both Span<T> and our Image<T> are strongly typed (the pixel type should be known at compile time), while System.Drawing (and I guess also Accord.Net) exposes a raw untyped void* buffer through BitmapData, and provide a PixelFormat enumeration which is runtime data. Currently we do not provide out of the box interop helpers to bridge the two, you need to figure out it yourself.
Bgra32 (thus Image<Bgra32>) is the counterpart of PixelFormat.Format32bppArgb which is the default AFAIK
Here is an example that wraps the raw memory data of System.Drawing.Bitmap as an Image<Bgra32>, without copying it, but this is rather advanced System.Memory stuff, you need to figure out how Memory<T> and MemoryManager<T> works.

[antonfirsov]

note to self (based on a gitter comment) We should update the MyGet installation docs:

Installation: Development releases are available via MyGet through NuGet. Go to Tools, Options, NuGet Package Manager, Package Sources and click on the "+" and set the name to something like "SixLabors MyGet" and set the source to: https://www.myget.org/F/sixlabors/api/v3/index.json then click Update, then OK. Then you can add ImageSharp via the NuGet Package Manager. In NuGet Package Manager, search for sixlabors.imagesharp.

[JimBobSquarePants]

People need to learn the NET ecosystem. MyGet have their own docs.

[JimBobSquarePants]

Gonna close this. We have fairly good docs now and can maintain them without a tracking issue