Please write good, like what I do

Sticklers unite! You have nothing to lose but your sense of proportion, and arguably you didn’t have a lot of that to begin with
Lynne Truss

Now that I am in my forties, for some strange inexplicable reason, use of grammar and consistency in written documentation has become more important than ever – Not to an extreme level of pedantry (I am sure that grammarians could rip this blog post to shreds), but the following, for instance, upset me more than is reasonable for a man who claims to be sane:

  • The incorrect use of ‘their‘, ‘there‘ or ‘they’re‘ – This irks me
  • Bullet points ending with random punctuation – They bother me
  • Long rambling and somewhat incoherent sentences that prove the author has been practising their cut-and-paste skills – What do they think this conveys to the reader?
  • Tables filled with useless boiler-plate information
  • Spelling mistakes! Use the spell checker! It is built in for goodness sake!

The Solution

It is clear to me that a guide is needed to help authors write in a clear, concise and consistent manner. Why? I am glad you asked:

  • Your audience expects a professional document. No ifs, no buts
  • Documents, especially Statement of Works (SOW), require clear and non-ambiguous language
  • It develops your understanding of the topic. When you are forced to consider every statement in your work, it creates a need to know your subject inside-out
  • Not everyone is a native English speaker. When English is taught as a second (or third) language, students are expected to learn grammatical rules, exceptions to those rules and sentence construction – imagine then what happens when they come across documents containing colloquialisms, incorrect choices of homophones or phrases that qualify as TLDR (too long, didn’t read)?

We have to consider some realities when putting a style guide together though. It needs to be usable and useful to busy people. There is no point in insisting that the author should follow rules like:

  • No prepositions at the end of a sentence
  • No split infinitives
  • Place a comma before a conjunction that joins two independent clauses

Fun fact: The first two in this list are considered as controversial in grammar as the use of the Oxford Comma!

What to do

Common sense dictates that text should be:

  • Consistent throughout
  • Clear, concise and precise
  • Effective in its use of punctuation
  • Relevant to the part of the document being read

Consistency

Consistency is king when writing formal documentation. Examples include:

  • Place full-stops (periods) at the end of all bullet points, or do not. Choose
  • Watch out for mixed Microsoft Word styles. Styles define fonts, their sizes and their spacing (along with other parameters). Do not mix styles; this is especially important if you cut-and-paste text from another document (inheritance)
  • Define an acronym on its first use. Then use only the acronym from then on throughout the whole document
  • Use Sentence Case or use Title Case in headings, but only use one or the other!

Clean and concise

Say what you have to say, but say it simply, clearly, and briefly. Then stop.

Think about each sentence and what message it conveys. Can it be taken another way than intended? Is it brief enough to communicate its message, but long enough to keep its meaning?

Punctuation

Punctuation is important:

“Now I must go and get on my lover” (original letter ending)

“Now I must go and get on, my lover” (hastily edited)!

Ronnie Barker, Porridge

Also, do not use an ampersand (&) in formal documentation unless it belongs to a brand name. For instance, ‘Tiffany&Co.’ or ‘AT&T’.

Relevance

If a decision has been made for a project in a design document, tell me why!

Justify the decision – Do not write a generic response like ‘Security requirement’.

Your answer tells me nothing; more importantly, when we close a project off three months later in a Post-Implementation Review (PIR), will we understand what you meant? Was the justification correct, or should we do something else in a future project?

Consider your audience. Do you honestly know who will read your work? Does the document explain concepts clearly enough so that it can be understood by:

  • Project Managers
  • Technical staff
  • C-Level executives
  • Stakeholders

Conclusion

It is not easy being the guy that cares about grammar. For many people (including myself), grammar and punctuation were not really taught in school; there wasn’t any explanation of relevance, just rules to follow.

My view is this: The purpose of grammar, punctuation and relevancy is politeness and forethought.

You need to demonstrate to the reader that you care about their experience, that you want them to share the journey with you and that you hold yourself to a high standard.

For now, I will leave you with a favourite stickler quote…

From now on, ending a sentence with a preposition is something up with which I will not put
Winston Churchill

Advertisements

THE DAY MY LAB DIED (CREDSSP ENCRYPTION ORACLE REMEDIATION)

Mr. Praline: Look, matey, I know a dead parrot when I see one, and I’m looking at one right now.

Owner: No no he’s not dead, he’s, he’s restin’!

My lab died!

It had been running quite happily for several weeks, then disaster struck…

Well to be precise (and a lot less dramatic), my Microsoft System Center Virtual Machine Manager (SCVMM) lost the ability to control any of my Hyper-V clusters.

I originally built this lab to prove a concept for a customer around a single instance of SCVMM, Azure Site Recovery (ASR) and stretched subnets across two datacentres. You’ll be able to read the results of this Proof of Concept (PoC) in another blog post.

The primary error was:

Error (2912)

An internal error has occurred trying to contact the ‘hyperv03.mydomain.corp’ server:

WinRM: URL: [http://hyperv03.mydomain.corp:5985], Verb: [INVOKE], Method: [GetVersion], Resource: [http://schemas.microsoft.com/wbem/wsman/1/wmi/root/scvmm/AgentManagement]

The request is not supported (0x80070032)

Followed by recommendations to check that Windows Remote Management (WinRM) was running (it was) and that the SCVMM agent was installed on the Hyper-V host (it was).

I went through the usual troubleshooting steps for WinRM:

  1. Test-WSMan – No errors
  2. Enable-PSRemoting – All good
  3. Enable-WSManCredSSP – No problems there
  4. Check local policy for ‘Allow Delegating Fresh Credentials’ – All set correctly

Then by chance, I searched using DuckDuckGo (privacy focused search engine) for “CredSSP the request is not supported” and found the following article:

https://www.tecklyfe.com/how-to-fix-authentication-error-function-not-supported-credssp-error-rdp/

Microsoft released an update for CredSSP in March 2018 (CVE-2018-0886) which patches a known vulnerability that allow remote code execution (CredSSP encryption Oracle remediation). This fix was updated in May (last month).

https://portal.msrc.microsoft.com/en-US/security-guidance/advisory/CVE-2018-0886

The simplest solution is to patch all servers immediately, but as we all know, patching takes time, and in a production environment with mandated maintenance windows, it takes planning.

A short-term workaround is available. Set the Group Policy value for “Computer Configuration/Administrative Templates/System/Credentials Delegation/Encrypted Oracle Remediation” to ‘Vulnerable’.

Note: Make sure that you understand the impact of setting this value which is detailed here:

https://support.microsoft.com/en-us/help/4093492/credssp-updates-for-cve-2018-0886-march-13-2018

Now that all my servers are patched, SCVMM is happily talking to my Hyper-V clusters.

I was lucky –  this only impacted a lab. Imagine if this was your production environment?

While it’s great that Microsoft are providing regular fixes for issues and bugs, it is a timely reminder that installing patches is not without some risk.

Ironically as my practice manager proofread this blog post, he realised that it would fix his issue with accessing his Virtual Machine in Azure!

 

Mr. Praline: Now that’s what I call a dead parrot.

Owner: No, no…..No, ‘e’s stunned!

Mr. Praline: STUNNED?!?

Calculating Standard Deviation using PowerShell

I have been reading a book on data science recently, and as a result I have had to revisit my high school maths!
One interesting thing I found is that there is more than one way to calculate the end result, and that the standard taught method may not be the most accurate!
The most accurate (according to the experts) is a method created by B.P.Welford, which is detailed in-depth in Donald Knuth’s ‘Art of computer programming’.

My brain thought “I wonder if anyone has implemented this in PowerShell”?

I found it in many difference languages, but not PowerShell, so I thought I would take someone else’s hard work and translate!

The site I choose is https://blog.logentries.com/2016/10/overview-of-online-algorithm-using-standard-deviation-example/#Welford

My version does not yet work as a class where you may ‘pop’ on another value dynamically, it assumes instead that you have the figures, and you would like to work out the Standard Deviation using either a Sample or a Population variance.

The code is as follows:


function Get-StandardDeviation {
    [CmdletBinding()]
    Param (
    # Array of double values
    [Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true,ValueFromPipeline=$true)]
    [ValidateNotNullOrEmpty()]
    [double[]]$Values
    )
    Begin {
        $count=0.0
        $mean=0.0
        $sum=0.0
    }#begin

    Process {
        foreach ($value in $values) {
            ++$count
            $delta = $mean + (($value - $mean) / $count)
            $sum += ($value - $mean) * ($value - $delta)
            $mean = $delta
        }#foreach
    } # process

    End {
        $VariancePopulation = $sum/($count)
        $VarianceSample = $sum/($count-1)
        $obj=[PSCustomObject]@{
            "VariancePopulation" = $VariancePopulation
            "VarianceSample" = $VarianceSample
            "STDEVPopulation" = [Math]::Sqrt($VariancePopulation)
            "STDEVSample" = [Math]::Sqrt($VarianceSample)
            "Mean" = $mean
            "Count" = $count
        }#obj
        Write-Output $obj
    } #end

}#function

To test this, create an array of doubles, and then use either method shown below to get the results.

$data = (50.0, 45.0, 55.0, 58.0, 43.0, 49.0, 50.0)</code>

Get-StandardDeviation -Values $data
$data | Get-StandardDeviation

Error: The Microsoft Online Services Module is not configured properly

What I was trying to achieve

I needed to use the MSOnline PowerShell Module to restore a deleted user from the Azure Active Directory (AAD) Recycle Bin. The replacement Module AzureAD does not (to my knowledge) have this functionality.

The Error

When trying to connect to AAD using the Connect-MsolService command, I received the following error:

Connect-MsolService : The Microsoft Online Services Module is not configured properly. Please uninstall and then reinstall the module.

I took the error messages advice, but to no avail.

Solution

The solution is in the registry…

Create a .reg file with the following content:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSOnlinePowerShell]
"Version"="1.0.0"
"InstallPath"="c:\\Program Files\\WindowsPowerShell\\Modules\\MSOnline\\1.0\\"
"InstallLanguage"="en-us"

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSOnlinePowerShell\Path]
"WebServiceUrl"="https://provisioningapi.microsoftonline.com/provisioningwebservice.svc"
"FederationProviderIdentifier"="microsoftonline.com"

Import the reg file, then retry the command.

Thank you to user ‘Froggy’ who commented the solution at the following URL: https://stackoverflow.com/questions/36672088/how-do-i-correctly-install-the-powershell-msonline-module-in-windows-8-1-enterpr

Richard

 

Connecting Virtual Networks in different Azure Subscriptions to an ExpressRoute circuit in Resource Manager

Scenario

I have an ExpressRoute circuit configured with a connection to a Version 2 (Resource Manager) Azure Virtual Network. I also have an additional Virtual Network in a different Subscription which I need to connect to the same circuit.

The Issue

The instructions on connecting another Virtual Network in a different Subscription are a little confusing. It’s also worth noting that some of the parameters are different now with the latest version of the PowerShell Azure cmdlets. The original instructions may be found at this URL: https://azure.microsoft.com/en-us/documentation/articles/expressroute-howto-linkvnet-arm/#connect-a-virtual-network-in-a-different-azure-subscription-to-an-expressroute-circuit

Continue reading

Automatically Naming Resources in an Azure Resource Management Template

Why?

Resource templates are a great concept, but are fraught with danger. Badly named resources and naming inconsistency across resources in different subscriptions can make it difficult to determine purpose.

If a resource such as a Virtual Network or a Storage Account is badly named in a resource template file, you may find that you have to rely on the icon pictures in the Azure portal to indicate what type of resources you are looking at.

What if you need to see at a glance:

  • What region the resource belongs to i.e. Australia East or Australia Southeast?
  • What environment the resource belongs to i.e. Production or Testing?
  • What type of resource it is?

The problem comes from trying to keep the names meaningful and consistent. How do you ensure that your naming standards are adhered to?

Scenario

In my case I would like to name resources as follows:

<Resource Prefix>_<Environment>_<Location>

For instance:

"Vnet_Prod_auSoutheast"
 Continue reading