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
Merge introduction into guides #692
Conversation
roll
commented
Feb 16, 2021
@@ -2,7 +2,7 @@ | |||
title: Guides Overview | |||
--- | |||
|
|||
## How to use this documentation | |||
**<big>How to use this documentation</big>** |
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.
It seems this heading level was exessive. I changed it to be in bold
@@ -1,5 +1,5 @@ | |||
--- | |||
title: Quick Start Guide | |||
title: Quick Start |
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 think just Quick Start is more like a standard name along with Installation or Getting Started (you skim for them usually)
@@ -15,7 +15,8 @@ pip install frictionless[sql] # to install a core plugin (optional) | |||
|
|||
The framework supports CSV, Excel, and JSON formats by default. Please use the command above to install a core plugin and add support for SQL, Pandas, HTML, and others (check the [list of Frictionless Framework plugins and their status](https://framework.frictionlessdata.io/docs/references/plugins-reference)). Usually, you don't need to think about it in advance–frictionless will display a useful error message about a missing plugin with installation instructions. | |||
|
|||
### Installation Troubleshooting | |||
### Troubleshooting |
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.
Shorten it as it's already under the "Installation" section hierarchically?
I also got problems with some other heading as it seems they to be too long for the table of contents:
Is it possible to shorten them too?
I think for highlighting text visually we can use other methods as in my opinion the main role of headings is to provide semantics (e.g. consider a blind person trying to navigate through them on a reader)
WDYT?
|
||
> For a more indepth example, use the [Overview Example](overview-example) | ||
> For more examples, use the [Basic Examples](basic-examples) |
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 think those examples are also very basic so I would rather keep like one example vs other examples difference instead of simple vs indepth
Here are my ideas and minor changes based on @lwinfree's work in #685:
|
Also, I think it will be critical then to add some diagrams/etc to the Introduction as, for now, it's the only text. For example, in the readme, I tried to be as concise as possible and provide bold/lists/colors/code blocks - https://github.com/frictionlessdata/frictionless-py/blob/master/README.md - to make it more fun to scan as one can just lose attention if it looks too texty I guess So I would rather go with "describe me Frictionless as I were 5 year old" style for introduction than user-stories in this form and a lot of plain text. And it will fit then better in the progressive documenatvion complexity concepts (starting from the simplest, ending with the most advanced) WDYT? |
@lwinfree I hope you will be back soon! |