-
Notifications
You must be signed in to change notification settings - Fork 726
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
Conversation
There was a problem hiding this 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
Oh didn't know about the capitalization guidelines, I'll definitely keep it lower going forward. |
Just to make sure, we did not move API reference under concepts in the end, right? |
Correct. API reference should remain where it is. It did not move. |
@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. |
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 |
@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. |
Description
Various updates to the docs: