New sp-usage-docs PnP Repository

Well, it’s not totally new – Vesa (@VesaJuvonen) gave me ownership of sp-usage-docs in May, but I’m just now getting to the point where I feel a blog post is merited.

A little background…

For quite a few years, Tom Resing (@resing) and I have been talking about the existing SharePoint documentation and who it serves. The move to docs.microsoft.com has opened up the documentation to the community for interaction and to suggest edits. This is a HUGE leap forward from the old MSDN and TechNet days, IMO.

But there has always seemed to be a gap in my mind. There is voluminous content for developers, end users, and admins, but not a lot for site owners and citizen developers. There’s also a lot of how, but less why. Several of us talked to Vesa about this at MVP Summit earlier this year, and we decided there should be an additional PnP-based effort to start creating content to fill this gap.

This gap reminds me of my old rantings about the Middle Tier in SharePoint – that stuff we did that was in between changing settings and writing code. Citizen developers have always been the heroes in this middle ground. Developers worry about them and end users love them. sp-usage-docs is aimed as much as that traditional middle ground as anything.

This is why we have a new Github repo called sp-usage-docs. Vesa added this description as we set it up: “SharePoint Documentation on usage and feature patterns for site owners and citizen developers”. sp-usage-docs makes sense in that it’s both specific enough and vague enough we can shape it into what it ought to be.

The idea is this will start as a Github repo, and if we succeed in creating useful content, it may become a tile on the SharePoint documentation page (like sp-dev-docs feeds a documentation area there). I believe we can get there, but I also feel like we should earn our way there. Thus my relatively quite publicizing of the repo to date.

If you saw “Github” above and thought that means it’s all about code, it absolutely isn’t. The reason we are using Github is there is a powerful engine in place to take content from a Github repo and move it into docs.microsoft.com. We want to piggyback on that engine, so Github makes good sense. I’ve written instructions in the repo for people who are new to Github, which hopefully make sense. (If they don’t, please ask your questions by adding a Question in the Issues list: see below. Or add a comment here.) All you really need to get started is a free Github account, so the platform knows who you are.

I asked quite a few of the heavyweights in this space to contribute content, but it was summer, everyone is busy, etc. The key is for any of us to create content that is useful for our target audiences, as we understand it at any time.

What an you do to help this effort? Well, as with most open source efforts, many of you will simply read the content as it becomes useful to you. That’s the way the model works, and that’s totally fine. But you can also be a contributor on several levels, which doesn’t need to take a lot of time or stress you out.

If you are looking for documentation about something which you feel fits this mold but are coming up short, here are some things you can do by raising an Issue in the Issues list:

• Explain what you need and why, but be realistic about the time frames in which you may see a result. This is an open source effort and we all have day jobs.
• Suggest an article or set of articles you’ve seen in blogs or other electronic formats which you think start(s) to get at the issue and might make a good addition here.
• Write something to fill the gap. Whether it’s a germ of an explanation or a full-fledged article, what you write can add value to the repository.

There are several options in the Issues list:

• Article Suggestion – Wish there was an article covering a topic near and dear to you? Suggest it here.
• Article Issue – See something wrong in an existing article? Suggest a fix here.
• Question – Have a general question? Ask it here.

Curious what types of articles we have so far? Check out these examples:

• Basics
  • What is a Content Type?
  • What is a Site Column?
• Making Decisions
  • Teams Site vs. Communication Site: Which one should I choose?
  • A Guided Tour Designed to Help You Select an Effective Navigation Strategy
  • Auto Apply Retention Labels in Office 365 Using Content Types and Metadata

This is The Best Community in Tech™, and I have great hopes for this repo. When our community focuses on something, it takes off like a rocket.

Above all, this is NOT a “Marc thing” – I just had conversations that got it moving. My role is to try to be ta catalyst (along with many others) and help shepherd the effort into being. Let me know what you think!

I want to thank the folks who have already made contributions or edits to improve the existing content:

• Susan Hanley (Github: SusanHanley, Twitter: SusanHanley)
• Eric Skaggs (Github: skaggej, Twitter: skaggej)
• Tom Daly (Github: tom-daly, Twitter: _tomdaly_)
• Joanne Klein (Github: joannecklein, Twitter: JoanneCKlein)

I expect this list will grow quickly. Don’t miss out!