Setup docsify for end user documentation #991
Conversation
Codecov Report
@@ Coverage Diff @@
## master #991 +/- ##
==========================================
+ Coverage 70.06% 70.09% +0.03%
==========================================
Files 141 141
Lines 8182 8157 -25
Branches 1854 1842 -12
==========================================
- Hits 5733 5718 -15
+ Misses 2162 2154 -8
+ Partials 287 285 -2
Continue to review full report at Codecov.
|
Page not starting on topWhen I scroll down one page and click another link in the sidebar, the page view does not start at the top, but the same position I used to be on on the last page.
The font in the sidebar navigation seems cut off.
Highlight linkWould it be possible to highlight the root of the page as we display the same content in mobile view - menu button at bottomWe might want to move the button to the top on mobile view as it probably will be not seen at the bottom.
Also the icon has no background, so it overlays the text and is hard to see. mobile view - top navigationThe 384px top navigation is breaking and overlaying the headline.
|
Fixed with the
I'm not understanding this feedback.
Ah, I figured it out. Should be fixed.
Fixed |
I'm sorry for not being clear here. The top of e.g. |
docs-user/README.md
Outdated
|
|
||
|  | ||
|
|
||
| Welcome to the user docs for [perf.html](https://perf-html.io), a web app that analyzes profiles from Firefox. [Visit the web app](https://perf-html.io), and follow the instructions to get started profiling. This guide has various documents and videos demonstrating how to get started profiling. Use the links on the left to dive into more details on how to use the product. Looking to contribute? Check out [github.com/devtools-html/perf.html](https://github.com/devtools-html/perf.html). |
There was a problem hiding this comment.
Use the links on the left to dive into more details on how to use the product.
This feels very obvious to me. Maybe we remove that part?
There was a problem hiding this comment.
Apparently I feel the need to explain how to use a sidebar. :D
| @@ -18,7 +18,7 @@ While samples provide a probabilistic view into the profiled program, markers pr | |||
|
|
|||
There was a problem hiding this comment.
The first is to increase the sampling rate.
What do you think about adding how? Just a short addition like ... manually in the settings. or something similar.
There was a problem hiding this comment.
This can skew the results.
Adding a short line about how maybe?
There was a problem hiding this comment.
The other way to increase the number of samples it run the code more often,
it --> is
There was a problem hiding this comment.
While samples provide a probabilistic view into the profiled program, markers provide a deterministic view into executing code. Markers are instrumentation that is collected every time an event happens. For instance, when clicking the mouse, the C++ implementation could call a function that collects the current mouse coordinates and timestamp of the event. This information would then be stored in the profiler's buffer.
As a non-native, I kind of had a hard time to follow that paragraph. Maybe changing instrumentation in Markers are instrumentation that is collected every time an event happens. could already loose it up a little.
There was a problem hiding this comment.
Ok, I rewrote it without the words "probabilistic" and "deterministic".
| @@ -18,7 +18,7 @@ While samples provide a probabilistic view into the profiled program, markers pr | |||
|
|
|||
| Samples are a general-purpose solution to understand what is going on in the code, while markers provide a specific opinionated view. A very fast mouse event will have a high probability of being missed on a low sampling rate, but will always be collected as a marker. The problem with markers is that they must be hand-instrumented in the code, and kept up to date. They are a great way for engineers with domain-specific information to surface more information about how a program is executing. The marker information can be cross-referenced with the samples to provide a better understanding of what code is doing. | |||
|
|
|||
| Markers can also be used for stack-like purposes as well. For instance when working with React or any front-end component system, the JavaScript stacks will all be framework internals. The internals are resolving work that was request by the components, but they do not directly map to the code that the component author wrote. To get around this, components could emit markers with start and end timestamps for when they are updated. These markers can then be turned into a chart that that shows how components are rendering according to a hierarchy, and how much time is being spent updating them. This labeled information can then be cross referenced with the statistically collected samples. | |||
| Markers can also be used for stack-like purposes as well. For instance when working with React or any front-end component system, the JavaScript stacks will all be framework internals. The internals are resolving work requested by the components, but they do not directly map to the code that the component author wrote. To get around this, components could emit markers with start and end timestamps for when they are updated. These markers can then be turned into a chart that shows how components are rendering according to a hierarchy, and how much time is being spent updating them. This labeled information can then be cross referenced with the statistically collected samples. | |||
|
|
|||
| ### Overhead and trade-offs with markers | |||
|
|
|||
There was a problem hiding this comment.
overhead—the sample -> overhead — the sample
Missing some blanks?
There was a problem hiding this comment.
I've been following the rule that em dashes do not require spaces between them, which looks odd in fixed-width fonts, but should be fine in the final presentation.
| @@ -1,32 +1,32 @@ | |||
| # Stack Samples and Call Trees | |||
|
|
|||
| The [profiler fundamentals](./profiler-fundamentals) details information about both samples and markers. While samples can collect any type of arbitrary information, this document explores one core idea about samples—that they can collect stacks. | |||
| The [profiler fundamentals](./guide-profiler-fundamentals.md) details information about both samples and markers. While samples can collect any type of arbitrary information, this document explores one core idea about samples—that they can collect stacks. | |||
There was a problem hiding this comment.
The [profiler fundamentals](./guide-profiler-fundamentals.md) details information about both samples and markers.
Feels like there is something missing?
There was a problem hiding this comment.
Yes, that is very poorly worded. I rewrote it.
Sorry, I'm still not seeing this or properly understanding it. |
|
Ok, all of your review comments should be addressed @zoepage Would you mind updating the status of the review? Generally our practice has been to make the status of the review to be:
|
|
Thank you for the explanation. I'll make sure to be more aligned with it in the future. :) |
This PR sets up docsify for the end-user documentation. I originally tried GitBook, but its static site generator is unmaintained, and I ran into several bugs that were already on file.
There were a few copy edits from the feedback from #983 mixed in the final commit with the setup. I will most likely follow-up with more work on the copy.
Here is a direct link to the deploy preview: https://deploy-preview-991--perf-html.netlify.com/docs/
This PR is in support of #805.
Another follow-up will be to integrate this into the perf.html UI.