C# Handbook Rewrite

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.