Published by Marco on 28. Apr 2016 23:20:17
------------------------------------------------------------------------

Encodo published its first C# Handbook and published it to "its web site"
 in 2008. At the time, we also
published to several other standard places and got some good, positive feedback.
Over the next year, I made some more changes and published new versions. The
latest version is 1.5.2 and is available from "Encodo's web site"
. Since then, though I've
made a few extra notes and corrected a few errors, but never published an
official version again.

This is not because Encodo hasn't improved or modernized its coding guidelines,
but because of several issues, listed below.

  * At 72 pages, it's really quite long
  * A more compact, look-up reference would be nice
  * It contains a mix of C#-specific, Encodo-specific and library-specific
    advice
  * It's maintained in Microsoft Word
  * Code samples are manually formatted
  * New versions are simply new copies in versioned folders (no source control)
  * Collaboration is nearly impossible
  * There is nothing about any .NET version newer than 3.5
  * There is no mention of any other programming language (e.g. TypeScript,
    JavaScript)
  * A lot of stuff is overly complicated (e.g. var advice) or just plain wrong
    (e.g. var advice)

To address these issues and to accommodate the new requirements, here's what
we're going to do:

  * Convert the entire document from Word to Markdown and put it in a Git
    repository
    * Collaboration? Pull requests. Branches.
    * Versioning? Standard diffing of commits.
    * Code samples? Automatic highlighting from GitLab (Encodo's internal
      server) or GitHub (external repository).
    
  * Separate the chapters into individual files and keep them shorter and more
    focused on a single topic
  * 
  * Separate all of the advice and rules into the following piles:
    * General programming advice and best practices
    * C#-specific
    * Encodo-specific
    * Library-specific (e.g. Quino)

These are the requirements and goals for a new version of the C# handbook.

The immediate next steps are:

   1. Convert current version from Microsoft Word to Markdown (done)
   2. Add everything to a Git repository (done)
   3. Overhaul the manual to remove incorrect and outdated material; address
      issues above (in progress)
   4. Mirror externally ("GitHub"  or "GitLab"
       or both)

I hope to have an initial, modern version ready within the next month or so.