Move .md files to the wiki about pnp-js-core

[patrick-rodgers]

Have been thinking on this one myself, I think looking at other projects there is no consensus. I think it would be cleaner to just point at the wiki, but my one other thought is that maintaining the docs in the project allows them to version along with the code. So that if I go back and for some reason pull v1.5 when the latest is v1.8 the 1.5 docs would still be relevant and correct for that version. I do see many projects just pointing to the wiki - which does give us one place to update and maintain - a big plus.

[alex-randall]

How about generated documentation?

.md for those, and sitting under /docs?

Also wouldn't it be nice in the future to have nice navigation/breadcrumb between all docs? These were the kinds of things I wanted to experiment with... Hard to do on wiki if it's manual approach.

I personally tend favor .md so that it can be automated perhaps in the future because everything is in one format and easy to automate (such as adding breadcrumbs, reusable content, version numbers to all pages)...

Wiki is pretty limited in as it's just a flat list of pages. No hierarchal folders at all (or at least last time I checked). Also, is there a way to deploy/automate things there? Maybe, but not easy.

On the other hand, wiki allows easy editing in the browser without having to do the whole setup your dev environment, forking, etc.

So plusses and minuses with both...

[pbjorklund]

You can clone the wiki as a git repo.

Perhaps "human related" things should go in the wiki and autogenerated into /docs.
Then we can link to the /docs/api/ files from the wiki when writing more human oriented documentation.
For instance usage examples will be hard to autogenerate if they are not written as comments directly in the source code; which is a bad idea.

So I suggest moving the .md files from the docs folder to the wiki and keep the .md files under /docs/api where they are until you finish the autogeneration of docs.

I can look through the API docs and extract things that will not be autogenerated into a start for samples in the wiki. That would let us overwrite the docs that are in /api/docs at a later time.

[pbjorklund]

@patrick-rodgers so, what do you think about my suggestion above? "moving the .md files from the docs folder to the wiki and keep the .md files under /docs/api where they are"

[patrick-rodgers]

do you mean create /docs/api in the wiki? If yes I think that is fine. We don't have an answer on doc generation so I am not sure it will matter yet where they live.

[patrick-rodgers]

I am going to close this one with the idea we will move the docs out of the project and into the wiki. We will still ship the readme in the npm package and update it to point to the wiki. Any objections?

[patrick-rodgers]

Did this work with #90.

[patrick-rodgers]

Closing this, other discussions on docs here