Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs structure and content #381

Merged
merged 32 commits into from
Mar 9, 2020
Merged

Update docs structure and content #381

merged 32 commits into from
Mar 9, 2020

Conversation

AaronCrawfis
Copy link
Collaborator

Description

Various updates to the docs:

  • Standard naming convention for all concepts: README.md under the concept folder
  • Move api docs into the respective concept folder and link reference to the api docs
  • Move redis configuration instructions into howtos
  • Remove quickstart section (redundant with getting started)

@AaronCrawfis AaronCrawfis changed the title Aacrawfi docs Update docs structure and content Mar 3, 2020
msfussell
msfussell previously approved these changes Mar 7, 2020
Copy link
Member

@msfussell msfussell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have looked over these changes and they look good. My one comment is that we did decide on not capitalizing all the words in title headings as per Azure docs guidance, whereas you have. It may be fine to leave this for now, but we should try to be consistent

@AaronCrawfis
Copy link
Collaborator Author

Oh didn't know about the capitalization guidelines, I'll definitely keep it lower going forward.

msfussell
msfussell previously approved these changes Mar 8, 2020
@yaron2
Copy link
Member

yaron2 commented Mar 8, 2020

Just to make sure, we did not move API reference under concepts in the end, right?

@msfussell
Copy link
Member

Correct. API reference should remain where it is. It did not move.

@AaronCrawfis
Copy link
Collaborator Author

@yaron2 @msfussell Actually in this branch I moved them into concepts.

I still want to make the argument for having both the overview and API reference under concepts. Currently from the dev experience if you want to use a building block: from reading about it for the first time, understanding how it works, and reading the API reference you'll need to look in 2-3 places. When I got started writing demos this was very confusing for me and why I opened #85. For me it makes sense to have the level 100 (what is it), level 200 (how do I use it) and level 300 (how does it work) all in one place. Then under references you can link to all the API docs, just like you do with the CLI docs.

Additionally this makes maintaining updates to the docs easier, so as a building block gets created or updated it will be one place to update content instead of 2.

But if you feel strongly the other way I'll revert back to the current structure.

@msfussell
Copy link
Member

msfussell commented Mar 9, 2020

Let' keep the API under the reference for now, since I feel there needs to be one place to find this reference. We will make sure there are plenty of links to the reference docs

@AaronCrawfis
Copy link
Collaborator Author

@msfussell I agree there needs to be a reference, but I see that more as a central appendix with links into all the applicable documents.

I'll update the api docs to go back under reference for now, but I'd like to continue this discussion and make the argument to centralize building block documentation all in one location.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants