From c5b8c7cf3def076607fd3e5b833b59f95e7a6998 Mon Sep 17 00:00:00 2001 From: Gareth Coles Date: Wed, 13 Jun 2018 17:28:11 +0100 Subject: [FAQ] Categorize and add FAQ about GitLab --- templates/main/info/faq.html | 362 ++++++++++++++++++++++++++----------------- 1 file changed, 218 insertions(+), 144 deletions(-) (limited to 'templates/main') 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 @@

Insert witty quip here

+

+ 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 + on GitLab? +

+ +
+
+

+ Starting Out with Python + + + + +

+
-
- I'm new to Python - how/where do I get started? + Is Python a good first language?

- 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.

- For more information on that and other resources, feel free to take a look at - our resources page. + 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!

- What's wrong with "Learn Python the Hard Way"? + I'm new to Python - how/where do I get started?

- 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. -

-

- 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 - XY Problem. + 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.

- For more information on why you should avoid Learn Python the Hard Way, you can have a look - at this article on the sopython wiki, - which enumerates the most egregious issues with it. + For more information on that and other resources, feel free to take a look at + our resources page.

@@ -120,128 +129,193 @@

-
-
- Why can't I import this module? -
-
-

- When finding yourself unable to import something in Python, you can follow these - steps to figure it out: -

-
    -
  • - Is the module part of Python's standard library? -
    • -
  • - If not, have you installed it? If the module is on PyPi, - you can install it using pip in a terminal: pip install module_name -
    • -
  • - If you think you've installed it, try upgrading it with pip in a terminal: - pip install -U module_name - Make sure there were no errors during - installation -
    • -
  • - If all else fails, make sure you've read the module documentation fully, and ensure - that you're following it correctly -
    • -
  • - 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 -
    • -
-
-
- -
-
- If I type "python" or "pip" into a terminal, I get "command not found". -
-
-

- That's not a question, but there's a few things you can look at to try to solve this. -

-
    -
  • - 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 -
    • -
  • - If you're on Windows, there's a good chance that python and - pip aren't what you actually need to run! Some options you could - try include py -3, python3 or python36 - if - one of these works, then you should be able to use py -3 -m pip, - pip3 or pip36 as well -
    • -
  • - 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 Homebrew - to install a more recent version of Python, which should be made available as - python3 -
    • -
-
-
- -
-
- What's PEP8? Should I care about code style? -
-
-

- Python Enhancement Proposal #8 - is known as the official Python style guide. It sets out a lot of very clear guidelines - which help you structure your code. -

-

- 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". -

-

- 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, - Google's Python Style Guide - is also widely used by Google engineers. -

-
-
- -
-
- Is Python a good first language? -
-
-

- 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. -

-

- 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! -

-
-
- -
-
- What does "real" Python development look like? -
-
-

- 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 - our projects? -

-
+
+ What's wrong with "Learn Python the Hard Way"? +
+
+

+ 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. +

+

+ 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 + XY Problem. +

+

+ For more information on why you should avoid Learn Python the Hard Way, you can have a look + at this article on the sopython + wiki, + which enumerates the most egregious issues with it. +

+
+ +
+ If I type "python" or "pip" into a terminal, I get "command not found". +
+
+

+ That's not a question, but there's a few things you can look at to try to solve this. +

+
    +
  • + 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 +
    • +
  • + If you're on Windows, there's a good chance that python and + pip aren't what you actually need to run! Some options you could + try include py -3, python3 or python36 - if + one of these works, then you should be able to use py -3 -m pip, + pip3 or pip36 as well +
    • +
  • + 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 Homebrew + to install a more recent version of Python, which should be made available as + python3 +
    • +
+
+ +
+ Why can't I import this module? +
+
+

+ When finding yourself unable to import something in Python, you can follow these + steps to figure it out: +

+
    +
  • + Is the module part of Python's standard + library? +
    • +
  • + If not, have you installed it? If the module is on + PyPi, + you can install it using pip in a terminal: pip install module_name +
    • +
  • + If you think you've installed it, try upgrading it with pip in a terminal: + pip install -U module_name - Make sure there were no errors during + installation +
    • +
  • + If all else fails, make sure you've read the module documentation fully, and ensure + that you're following it correctly +
    • +
  • + 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 +
    • +
+
+ +
+ What's PEP8? Should I care about code style? +
+
+

+ Python Enhancement Proposal #8 + is known as the official Python style guide. It sets out a lot of very clear guidelines + which help you structure your code. +

+

+ 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". +

+

+ 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, + Google's Python Style Guide + is also widely used by Google engineers. +

+
+ +
+

+ Community Questions + + + + +

+
+ +
+ Why did you move to GitLab? Do you hate Microsoft? +
+
+

+ While many of our users do prefer to work on Linux, we don't hate Microsoft. While + + the news about Microsoft's acquisition of GitHub + + 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: +

+
    +
  • + Prior to moving to GitLab, our development efforts were split among three services: + ClickUp for issue tracking, + GitHub for code storage and collaboration, + and Travis 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. +
    • +
  • + 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. +
    • +
  • + In the vast majority of cases where GitHub and GitLab solve the same problem or + have a similar feature, GitLab does it better. +
    • +
  • + GitLab has had free private repositories for some time now, and these are convenient + for us to store internal documentation and tasks in. +
    • +
  • + 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. +
    • +
+
+ +
+

+ Misc. Questions + + + + +

+
+ +
+ What does "real" Python development look like? +
+
+

+ 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 + our projects? +

-- cgit v1.2.3