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

Merge introduction into guides #692

Merged
merged 6 commits into from Feb 17, 2021
Merged

Merge introduction into guides #692

merged 6 commits into from Feb 17, 2021

Conversation

roll
Copy link
Member

@roll roll commented Feb 16, 2021

docs

@@ -2,7 +2,7 @@
title: Guides Overview
---

## How to use this documentation
**<big>How to use this documentation</big>**
Copy link
Member Author

@roll roll Feb 16, 2021

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
Copy link
Member Author

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
Copy link
Member Author

@roll roll Feb 16, 2021

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:

toc

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)
Copy link
Member Author

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

@roll
Copy link
Member Author

roll commented Feb 16, 2021

Hi @lwinfree @sapetti9,

Here are my ideas and minor changes based on @lwinfree's work in #685:

  • merging Introduction into Guides (as not it's not a copy of the Readme so there is no reason to distinguish it from the guides. And we will get more space in the top-bar for notebooks/videos/etc)
  • proposing Basic Examples instead of Overview Examples not to clash with Guides Overview
  • add also comment to the PR itself

@roll
Copy link
Member Author

roll commented Feb 16, 2021

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?

@roll
Copy link
Member Author

roll commented Feb 16, 2021

I was thinking a lot and finally decided to make a try on the intro small tweaks. The only goal was to make it more light-weighted structurally/visually to a new user:

intro

WDYT?

@roll
Copy link
Member Author

roll commented Feb 17, 2021

@lwinfree
This PR starts to block me so I'm going to merge this and then let's discuss and revert changes we're not agreed on. Basically, it's anyway easier to work on top of the docs changes as I did with your PR (merging as it is and then proposing updates)

I hope you will be back soon!

@roll roll merged commit 9c65d53 into master Feb 17, 2021
@roll roll deleted the merge-introduction-top-level branch February 17, 2021 08:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

None yet

1 participant