What documentation would you like to see?

[pkbullock]

Hi All,

I am looking into the documentation on this library, and have the following ideas:

• Examples of creating the client context
• Show examples of working with SharePoint List Items and Documents
• Describe the extension methods areas
• Examples of working with the Microsoft Graph
• Examples of working with Microsoft Teams
• Examples of working with Modernization Tooling
• Examples of working with the PnP Provisioning Engine
• Examples of working with PnP Core SDK within the PnP Framework

Examples will likely use Polyglot/console to get working examples/samples available from the above list.

Is there anything else you would like to see?

[Adam-it]

Soooooo:

1. Please don't focus only on examples 😅 I mean those are needed and awesome but maybe those could be part of the repo in some sample folder each with it's own readme and in wiki just a general summary about them 🤔.
2. For sure some general explanation on what? and why would you wanna use? What are the pros and cons?
3. A bit about the tech behind the hood. What kind of technology is used? Is it 'fresh' and supported?
4. Some section with links or resources that folks may find on the web that promoted this tech. Maybe some link to a blog or demo on PnP call
5. Some references to the Microsoft 365 and Power Platform Community
6. Use some emojis 😜

I really liked how the M365 developer proxy wiki is handled. It has many information and it is very clean. I think our CLI for Microsoft 365 is a good example 🤔 (I hope 😅), we focused more on how we handle the repo and PRs, how to contribute properly, what are the steps etc. so it is easy for the contributors. Not so long ago I added wiki for the viva connections toolkit, not saying it is perfect or a good example but maybe it will be some inspiration for you, or you may find some approach useful 🤔.
BTW thanks for taking this 👍 Handling documentation is never easy and nobody wants to do it 😅. You Rock 🤩.

[Adam-it]

Sooo checking here again with more news 😉. I think it is worth mentioning that in CLI not so long ago we decided to step away from GitHub Wiki and move all of our docs (also the contributing guidance which currently is in the wiki still) to our website. Also from the 'rumors' I heard and I think @garrytrinder may confirm 😋 M365 developer proxy is also planning at some point to stop using GitHub wiki and migrate to some web equivalent on GitHub pages.
The main reasons are:

• the search engine in GitHub wiki is quite bad allowing only to search by page title and only if your query is precise (not allowing any typos or similar words etc.). On your own website you may do whatever you want and also implement custom search engines based on AI that will give the answer without looking for it on your own. That's what we did in CLI for Microsoft 365.
• Wiki is 'detached' from the repo. Meaning you need specific permissions to update it. Usually, only maintainers have those permissions. So it is not possible for a contributor to contribute, and open a PR for example to fix typos in the docs. Also, docs may not be extended together with the feature. So it is impossible to implement some logic and code and update the docs in the same PR as the wiki is not part of the source code.
• Lack of investment in GitHub Wiki. It is quite an old GitHub feature and nothing new is showing up
• GitHub Wiki rather pure UI experience. On your own website you may make it look however you want making it more appealing and interesting for the end user.
• GitHub Wiki navigation is quite poor. Does not work well when you have a long page, and does not move together with the scroll making it impossible to quickly jump between headings
• as we did some research many others, including many PnP, open source projects, don't use GitHub wiki and rather maintain the docs as a separate website

[garrytrinder]

Wiki is a good place to start but soon become limited.

We used Wiki for speed but do have plans to move to more appropriate docs platform as we start to hit its limits.

To add to what @Adam-it has already said:

• We found out recently that in repos that have under 500 stars, the pages are not indexed by search engines (see remark on https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis)
• Wikis do not support pull requests so you can't accept community contributions, only maintainers can make edits.
• We found that the Wiki tab can get hidden into the ... menu on certain screen sizes, I've seen this happen on desktop as well, so can be harder to find.

I manage our wiki using VSCode and treat it like any other git repo rather than using the UI. I use local branches to separate my changes and merge them on release day into local master and push the changes just after we release the code.

[pkbullock]

These are awesome suggestions, for now in terms of a portal, I am using a DocFx site much like PnP Core SDK, Samples etc, this is already in place and I am populating it. Interesting about the Wiki limits.

For me this is a slow burn project, on top of other activities. Ironically, I need to learn the SDK to document it especially to make operational examples of code, but that's OK.

I'm thinking of writing a DocFx plugin/PS script (whichever does the job optimally) that takes a juniper notebook and extracts a code block, that way I can write in one place that can be easily checked and it would reflect in the markdown files.