diff options
| author |  Gareth Coles <[email protected]> | 2018-06-13 17:28:11 +0100 |
|---|---|---|
| committer | Gareth Coles <[email protected]> | 2018-06-13 17:28:11 +0100 |
| commit | c5b8c7cf3def076607fd3e5b833b59f95e7a6998 (patch) | |
| tree | 27217c8635aad3d04846e7fd31bdde1c9481cc2c | |
| parent | Compile as much JS with Gulp as possible (diff) | |
[FAQ] Categorize and add FAQ about GitLab
| -rw-r--r-- | templates/main/info/faq.html | 362 |
1 files changed, 218 insertions, 144 deletions
diff --git a/templates/main/info/faq.html b/templates/main/info/faq.html index b9e4cf08..e742f317 100644 --- a/templates/main/info/faq.html +++ b/templates/main/info/faq.html @@ -16,44 +16,53 @@ <p class="uk-article-meta"> Insert witty quip here </p> + <p> + These are some of the most-asked questions we get on a day-to-day basis. If you have a + question, be sure to check this page and see if we've answered it already. If you'd like to + suggest an entry to this page, why not submit a merge request + <a href="https://gitlab.com/python-discord/projects/site">on GitLab</a>? + </p> + + <div uk-grid class="uk-grid uk-grid-match"> + <div class="uk-width-1-1@s"> + <h2 class="uk-heading-divider" id="starting-out"> + Starting Out with Python + + <a href="#starting-out" class="uk-text-primary uk-float-right" title="Permanent link to this header"> + <i class="far fa-link"></i> + </a> + </h2> + </div> - <div uk-grid class="uk-grid uk-grid-divider uk-grid-match"> <div class="uk-width-1-3@m"> - <strong>I'm new to Python - how/where do I get started?</strong> + <strong>Is Python a good first language?</strong> </div> <div class="uk-width-2-3@m"> <p> - How you get started with Python is very much going to depend on your prior programming - experience. If you're already an experienced programmer, you should should have no - trouble following pretty much any guide out there - but for true beginners, we recommend - full-on tutorials such as Automate the Boring Stuff with Python. + In our opinion, yes it is. It's a very powerful language, but it will force you to + write readable code and it's designed to allow you to write code very quickly, without + you having to keep your head in a book for hours on end. </p> <p> - For more information on that and other resources, feel free to take a look at - <a href="{{ url_for("main.info.resources") }}">our resources page</a>. + Python is used as a teaching language in many schools, colleges and universities - but + it's a very capable language that is suitable for many real-world tasks as well, and + it's only gaining in popularity! </p> </div> <div class="uk-width-1-3@m"> - <strong>What's wrong with "Learn Python the Hard Way"?</strong> + <strong>I'm new to Python - how/where do I get started?</strong> </div> <div class="uk-width-2-3@m"> <p> - Learn Python the Hard Way, Zed Shaw's most infamous work, is largely considered by the - Python community to be poor-quality and misleading in general. This is due to numerous - issues with the material, which include being extremely opinionated and sometimes - condescending, out of date, confusing and even wildly incorrect in some places. - </p> - <p> - Learners that have used Learn Python the Hard Way as their primary learning material often - find themselves confused and asking questions that really don't make that much sense - it's - also been observed that learners in this position tend to suffer heavily from the infamous - <a href="http://xyproblem.info/">XY Problem</a>. + How you get started with Python is very much going to depend on your prior programming + experience. If you're already an experienced programmer, you should should have no + trouble following pretty much any guide out there - but for true beginners, we recommend + full-on tutorials such as Automate the Boring Stuff with Python. </p> <p> - For more information on why you should avoid Learn Python the Hard Way, you can have a look - at <a href="https://sopython.com/wiki/LPTHW_Complaints">this article on the sopython wiki</a>, - which enumerates the most egregious issues with it. + For more information on that and other resources, feel free to take a look at + <a href="{{ url_for("main.info.resources") }}">our resources page</a>. </p> </div> @@ -120,128 +129,193 @@ </p> </div> - <div uk-grid class="uk-grid uk-grid-divider uk-grid-match"> - <div class="uk-width-1-3@m"> - <strong>Why can't I import this module?</strong> - </div> - <div class="uk-width-2-3@m"> - <p> - When finding yourself unable to import something in Python, you can follow these - steps to figure it out: - </p> - <ul> - <li> - Is the module part of <a href="https://docs.python.org/3/library/">Python's standard library</a>? - </li> - <li> - If not, have you installed it? If the module <a href="https://pypi.org/search/">is on PyPi</a>, - you can install it using pip in a terminal: <code>pip install module_name</code> - </li> - <li> - If you think you've installed it, try upgrading it with pip in a terminal: - <code>pip install -U module_name</code> - Make sure there were no errors during - installation - </li> - <li> - If all else fails, make sure you've read the module documentation fully, and ensure - that you're following it correctly - </li> - <li> - If you're sure that you've done everything correctly, you may have found a bug - come - and chat to us, and we might recommend that you report your problem to the developer - </li> - </ul> - </div> - </div> - - <div uk-grid class="uk-grid uk-grid-divider uk-grid-match"> - <div class="uk-width-1-3@m"> - <strong>If I type "python" or "pip" into a terminal, I get "command not found".</strong> - </div> - <div class="uk-width-2-3@m"> - <p> - That's not a question, but there's a few things you can look at to try to solve this. - </p> - <ul> - <li> - If you're on Windows, the python installer has an option labelled "Add to PATH" - - Make sure you check this when you install python. If you forgot to do that the - first time, then the easiest way to solve this problem is to reinstall Python - </li> - <li> - If you're on Windows, there's a good chance that <code>python</code> and - <code>pip</code> aren't what you actually need to run! Some options you could - try include <code>py -3</code>, <code>python3</code> or <code>python36</code> - if - one of these works, then you should be able to use <code>py -3 -m pip</code>, - <code>pip3</code> or <code>pip36</code> as well - </li> - <li> - If you're on a Mac, Python comes with the OS - however, it's quite likely to be - an old version. You can solve this by using <a href="https://brew.sh">Homebrew</a> - to install a more recent version of Python, which should be made available as - <code>python3</code> - </li> - </ul> - </div> - </div> - - <div uk-grid class="uk-grid uk-grid-divider uk-grid-match"> - <div class="uk-width-1-3@m"> - <strong>What's PEP8? Should I care about code style?</strong> - </div> - <div class="uk-width-2-3@m"> - <p> - <a href="https://www.python.org/dev/peps/pep-0008/">Python Enhancement Proposal #8</a> - is known as the official Python style guide. It sets out a lot of very clear guidelines - which help you structure your code. - </p> - <p> - One of the most useful things you can do when writing your code is to follow a style - guide. It makes it easier to read your code overall, but a consistent style guide - is very important as it means that everyone that contributes to your project is - writing code in the same style - meaning everyone will be able to read it. As PEP - itself reads: "A foolish consistency is the hobgoblin of little minds". - </p> - <p> - PEP8 isn't the only style guide available to you, but it is the most widely used - and best-understood of them - and for that reason, we do recommend you use it. That - said, - <a href="https://google.github.io/styleguide/pyguide.html">Google's Python Style Guide</a> - is also widely used by Google engineers. - </p> - </div> - </div> - - <div uk-grid class="uk-grid uk-grid-divider uk-grid-match"> - <div class="uk-width-1-3@m"> - <strong>Is Python a good first language?</strong> - </div> - <div class="uk-width-2-3@m"> - <p> - In our opinion, yes it is. It's a very powerful language, but it will force you to - write readable code and it's designed to allow you to write code very quickly, without - you having to keep your head in a book for hours on end. - </p> - <p> - Python is used as a teaching language in many schools, colleges and universities - but - it's a very capable language that is suitable for many real-world tasks as well, and - it's only gaining in popularity! - </p> - </div> - </div> - - <div uk-grid class="uk-grid uk-grid-divider uk-grid-match"> - <div class="uk-width-1-3@m"> - <strong>What does "real" Python development look like?</strong> - </div> - <div class="uk-width-2-3@m"> - <p> - Python is a very versatile language, and a real-life application using it can take - many forms. That said, we do plenty of Python development here ourselves. If - you're curious about this question, then why not take a look at - <a href="https://gitlab.com/python-discord">our projects</a>? - </p> - </div> + <div class="uk-width-1-3@m"> + <strong>What's wrong with "Learn Python the Hard Way"?</strong> + </div> + <div class="uk-width-2-3@m"> + <p> + Learn Python the Hard Way, Zed Shaw's most infamous work, is largely considered by the + Python community to be poor-quality and misleading in general. This is due to numerous + issues with the material, which include being extremely opinionated and sometimes + condescending, out of date, confusing and even wildly incorrect in some places. + </p> + <p> + Learners that have used Learn Python the Hard Way as their primary learning material often + find themselves confused and asking questions that really don't make that much sense - it's + also been observed that learners in this position tend to suffer heavily from the infamous + <a href="http://xyproblem.info/">XY Problem</a>. + </p> + <p> + For more information on why you should avoid Learn Python the Hard Way, you can have a look + at <a href="https://sopython.com/wiki/LPTHW_Complaints">this article on the sopython + wiki</a>, + which enumerates the most egregious issues with it. + </p> + </div> + + <div class="uk-width-1-3@m"> + <strong>If I type "python" or "pip" into a terminal, I get "command not found".</strong> + </div> + <div class="uk-width-2-3@m"> + <p> + That's not a question, but there's a few things you can look at to try to solve this. + </p> + <ul> + <li> + If you're on Windows, the python installer has an option labelled "Add to PATH" - + Make sure you check this when you install python. If you forgot to do that the + first time, then the easiest way to solve this problem is to reinstall Python + </li> + <li> + If you're on Windows, there's a good chance that <code>python</code> and + <code>pip</code> aren't what you actually need to run! Some options you could + try include <code>py -3</code>, <code>python3</code> or <code>python36</code> - if + one of these works, then you should be able to use <code>py -3 -m pip</code>, + <code>pip3</code> or <code>pip36</code> as well + </li> + <li> + If you're on a Mac, Python comes with the OS - however, it's quite likely to be + an old version. You can solve this by using <a href="https://brew.sh">Homebrew</a> + to install a more recent version of Python, which should be made available as + <code>python3</code> + </li> + </ul> + </div> + + <div class="uk-width-1-3@m"> + <strong>Why can't I import this module?</strong> + </div> + <div class="uk-width-2-3@m"> + <p> + When finding yourself unable to import something in Python, you can follow these + steps to figure it out: + </p> + <ul> + <li> + Is the module part of <a href="https://docs.python.org/3/library/">Python's standard + library</a>? + </li> + <li> + If not, have you installed it? If the module <a href="https://pypi.org/search/">is on + PyPi</a>, + you can install it using pip in a terminal: <code>pip install module_name</code> + </li> + <li> + If you think you've installed it, try upgrading it with pip in a terminal: + <code>pip install -U module_name</code> - Make sure there were no errors during + installation + </li> + <li> + If all else fails, make sure you've read the module documentation fully, and ensure + that you're following it correctly + </li> + <li> + If you're sure that you've done everything correctly, you may have found a bug - come + and chat to us, and we might recommend that you report your problem to the developer + </li> + </ul> + </div> + + <div class="uk-width-1-3@m"> + <strong>What's PEP8? Should I care about code style?</strong> + </div> + <div class="uk-width-2-3@m"> + <p> + <a href="https://www.python.org/dev/peps/pep-0008/">Python Enhancement Proposal #8</a> + is known as the official Python style guide. It sets out a lot of very clear guidelines + which help you structure your code. + </p> + <p> + One of the most useful things you can do when writing your code is to follow a style + guide. It makes it easier to read your code overall, but a consistent style guide + is very important as it means that everyone that contributes to your project is + writing code in the same style - meaning everyone will be able to read it. As PEP + itself reads: "A foolish consistency is the hobgoblin of little minds". + </p> + <p> + PEP8 isn't the only style guide available to you, but it is the most widely used + and best-understood of them - and for that reason, we do recommend you use it. That + said, + <a href="https://google.github.io/styleguide/pyguide.html">Google's Python Style Guide</a> + is also widely used by Google engineers. + </p> + </div> + + <div class="uk-width-1-1@s"> + <h2 class="uk-heading-divider" id="community"> + Community Questions + + <a href="#community" class="uk-text-primary uk-float-right" title="Permanent link to this header"> + <i class="far fa-link"></i> + </a> + </h2> + </div> + + <div class="uk-width-1-3@m"> + <strong>Why did you move to GitLab? Do you hate Microsoft?</strong> + </div> + <div class="uk-width-2-3@m"> + <p> + While many of our users do prefer to work on Linux, we don't hate Microsoft. While + <a href="https://www.theregister.co.uk/2018/06/04/microsoft_buys_github/"> + the news about Microsoft's acquisition of GitHub + </a> + did prompt us to initially mirror our GitHub repositories to GitLab for safety, we didn't + outright make the move because of the acquisition - in fact, some of our staff members + had been suggesting we use it from the start! Here's some of the reasons we decided + to move: + </p> + <ul> + <li> + Prior to moving to GitLab, our development efforts were split among three services: + <a href="https://clickup.com/">ClickUp</a> for issue tracking, + <a href="https://github.com/">GitHub</a> for code storage and collaboration, + and <a href="https://clickup.com/">Travis</a> for continuous integration and testing. + GitLab is a fantastic alternative to all of these services, and moving to it has allowed + us to consolidate our efforts in one place. + </li> + <li> + For a long time now, GitLab has been innovating on features and pushing them to production + much faster than GitHub. Using GitLab gives us far more options when it comes to issue + management, merge requests, continuous integration and deployment - to name + a few things. + </li> + <li> + In the vast majority of cases where GitHub and GitLab solve the same problem or + have a similar feature, GitLab does it better. + </li> + <li> + GitLab has had free private repositories for some time now, and these are convenient + for us to store internal documentation and tasks in. + </li> + <li> + GitLab is fully open-source and quite easy to host yourself. In the event that the + public platform ends up dying or being abused by its staff, we can simply spin + up our own instance and keep on working as if there were no problems. + </li> + </ul> + </div> + + <div class="uk-width-1-1@s"> + <h2 class="uk-heading-divider" id="misc"> + Misc. Questions + + <a href="#misc" class="uk-text-primary uk-float-right" title="Permanent link to this header"> + <i class="far fa-link"></i> + </a> + </h2> + </div> + + <div class="uk-width-1-3@m"> + <strong>What does "real" Python development look like?</strong> + </div> + <div class="uk-width-2-3@m"> + <p> + Python is a very versatile language, and a real-life application using it can take + many forms. That said, we do plenty of Python development here ourselves. If + you're curious about this question, then why not take a look at + <a href="https://gitlab.com/python-discord">our projects</a>? + </p> </div> </div> </article> |