Quick start document

[KarolKaczmarek]

There was lots of improvements in all our contributing and other guidelines and that's great, we have very good coverage now, however there was feedback those documents grew to the point no one will read all of them before contributing. I tend to agree, I think they will act more as a reference if someone encounters specific problem (e.g. using our test templates, resolving conflicts etc.).

Navigating through all guidelines can be a little bit overwhelming initially, so there was proposition to create a "quick start" document with only info absolutely necessary to get started with contributing to DSC Resources. It could also have pointers to more advanced topics to refer to later.

We could ensure it's concise by adding a test to check it doesn't exceed certain number of words (1000 sounds like an easy 5 minute read for most people).

Question: Do you think this is something what would be useful or we are simply trying to solve the problem of too much documentation by adding yet another document?

[PlagueHO]

@KarolKaczmarek - a quick start guide actually sounds like a pretty good idea to me.

[johlju]

I thought about this for new contributors, there are tons of documentation to read through which can be overwhelming. The down side to have a quick start is that is a separate document which need to be maintained on top of the other documentation.

In SqlServerDs we tried to make it a little easier to at least find the documentation; https://github.com/PowerShell/SqlServerDsc/blob/dev/README.md#contributing. But that are still a lot of documentation to browse through.

I think we have a lot och great documentation, but maybe we should make it task oriented instead so it is easier to find? For example CONTRIBUTING.md and GettingStartedWithGithub have both documentation in the same area (Pull Request). Maybe create for example separate files for 'Getting started with GitHub', 'How to create a unit test', 'How to work with issues' and 'How to work with Pull Requests', and so on. CONTRIBUTING.md can then link to the files, together with minor text (quick start) which link to a document with more details.

[PlagueHO]

We do have a lot of different documents and sometimes when I want to find something I usually have to go through several before finding the right one.

I'm OK with separating the files but they do need to be some how grouped together. Perhaps use folders? Or prefixes: "GitHub - How to work with Pull Requests.md", "GitHub - Getting Started.md" - otherwise it'll get pretty busy in there and hard to find anything).

But what we also probably want is a table of contents pulling everything together.

[johlju]

Yes, I agree it is hard do find stuff, I have the same problem. Maybe this will help make it easier to find what one is looking for.

Yes I agree of the naming, but not sure about folders. 🤔 Folders tend to make it hard to find things too, it is also harder to reorganize (many links break). Maybe one folder for all documentation (files using your proposed naming), and CONTRIBUTING.md in the root of the repo? My thought was that the table of contents could be in CONTRIBUTING.md, linking to each .md file.

[johlju]

We should also add a Glossary.md as per issue #201

[stale[bot]]

This issue has been automatically marked as stale because it has not had activity from the community in the last 30 days. It will be closed if no further activity occurs within 10 days. If the issue is labelled with any of the work labels (e.g bug, enhancement, documentation, or tests) then the issue will not auto-close.

[johlju]

Added some quick-start steps here that can be added to a quick-start documentation. https://github.com/PowerShell/SqlServerDsc/issues/1173#issuecomment-403142729