Skip to content

Conversation

Yoyozilla
Copy link
Contributor

@Yoyozilla Yoyozilla commented Apr 24, 2019

This is in response to some of the feedback we have gotten.
The documents today are more like feature description and overview vs how-to.
How-to should be scenario/task focused to teach people how to complete a tast/scenario.
I am moving the doc ToC reflect more of this.

@Yoyozilla Yoyozilla requested a review from wiwei April 24, 2019 20:52
@wiwei
Copy link
Contributor

wiwei commented Apr 24, 2019

/azp run mrtk_docs

@azure-pipelines
Copy link

Azure Pipelines successfully started running 1 pipeline(s).

@wiwei
Copy link
Contributor

wiwei commented Apr 24, 2019

Waiting on docs run, changes seem okay.

@wiwei
Copy link
Contributor

wiwei commented Apr 24, 2019

Can you fix the doc build breaks please:

Build failed.
[19-04-24 10:10:29.536]Warning:BuildCommand.BuildCore.Build Document.CompilePhaseHandlerWithIncremental.TocDocumentProcessor.Prebuild.BuildTocDocumentUnable to find either toc.yml or toc.md inside Documentation/. Make sure the file is included in config file docfx.json!
[19-04-24 10:10:29.536]Error:BuildCommand.BuildCore.Build Document.Load.TocDocumentProcessorD:\a\1\s\Documentation\toc.yml is not a valid TOC File: D:\a\1\s\Documentation\toc.yml is not a valid TOC file, detail: (Line: 11, Col: 5, Idx: 212) - (Line: 11, Col: 5, Idx: 212): While parsing a block collection, did not find expected '-' indicator..
[19-04-24 10:10:29.536]Error:BuildCommand.BuildCore.Build Document.Load.TocDocumentProcessorUnable to load file 'Documentation/toc.yml' via processor 'TocDocumentProcessor': D:\a\1\s\Documentation\toc.yml is not a valid TOC File: D:\a\1\s\Documentation\toc.yml is not a valid TOC file, detail: (Line: 11, Col: 5, Idx: 212) - (Line: 11, Col: 5, Idx: 212): While parsing a block collection, did not find expected '-' indicator..
1 Warning(s)

@Yoyozilla
Copy link
Contributor Author

/azp run mrtk_docs

@azure-pipelines
Copy link

Azure Pipelines successfully started running 1 pipeline(s).

@julenka
Copy link
Contributor

julenka commented Apr 25, 2019

@Yoyozilla Sorry, but what is this restructuring exactly? Is it the table of contents for github.io page? Could you provide a little bit more detail in the pull request please?

@julenka julenka changed the title re structure [documentation] re-structure table of contents Apr 25, 2019
@Yoyozilla
Copy link
Contributor Author

Yoyozilla commented Apr 25, 2019

@julenka This is in response to some of the feedback we have gotten.
The documents today are more like feature description and overview vs how-to.
How-to should be scenario/task focused to teach people how to complete a tast/scenario.
I am moving the doc ToC reflect more of this.

@Yoyozilla
Copy link
Contributor Author

/azp run mrtk_docs

@azure-pipelines
Copy link

Azure Pipelines successfully started running 1 pipeline(s).

@Yoyozilla
Copy link
Contributor Author

/azp run mrtk_docs

@azure-pipelines
Copy link

Azure Pipelines successfully started running 1 pipeline(s).

@Yoyozilla Yoyozilla requested a review from thalbern April 25, 2019 20:39
@julenka
Copy link
Contributor

julenka commented Apr 25, 2019

/azp run mrtk_docs

@azure-pipelines
Copy link

Azure Pipelines successfully started running 1 pipeline(s).

@julenka
Copy link
Contributor

julenka commented Apr 25, 2019

Hi yoyo, it looks like the docs build is still failing. The error is:

(Documentation/toc.yml#L0) Invalid file link:(~/Documentation/README.md).

@wiwei
Copy link
Contributor

wiwei commented Apr 25, 2019

I think also the general feedback was to have in the PR description what is being changed and why. (If you could take your response to Julia's feedback and paste it into the PR description that would be good)

@wiwei
Copy link
Contributor

wiwei commented Apr 25, 2019

Per our offline chat, I deleted the stale migration readme, but this causes a merge conflict in yours because I had to update the toc.yml

#4090

@thalbern
Copy link
Contributor

/azp run mrtk_docs

@thalbern
Copy link
Contributor

@Yoyozilla ignore if you know / do this already: you can run docfx locally - it just takes a couple of seconds. that way you can easier fix issues / iterate on issues in this PR without having to wait for the CI builder all the time :)

@Yoyozilla
Copy link
Contributor Author

/azp run mrtk_docs

@azure-pipelines
Copy link

Azure Pipelines successfully started running 1 pipeline(s).

@Yoyozilla Yoyozilla requested a review from thalbern April 28, 2019 05:37
href: TODO.md
- name: Moving your project from HTK to MRTK
href: HTKToMRTKPortingGuide.md
- name: How-to
Copy link
Contributor

Choose a reason for hiding this comment

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

Unless someone is actually going to do this in the next few days, I recommend not adding new TODOs.

These are very frustrating to read (as a consumer) and are easy to forget about (as a producer)

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm going to go ahead and merge this PR as-is to get it in, then add this to my incoming docs PR.

@keveleigh keveleigh merged commit 0d5ff9b into mrtk_development May 3, 2019
@keveleigh keveleigh deleted the Yoyozilla-patch-1 branch May 3, 2019 21:40
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.

5 participants