# COMP0233 - Day 6 (17th November 2022)

:::info
## :tada: Welcome to the sixth day! :books: Documentation, Finding Errors and Debugging

### Today
Today we will look at
- :books: Documentation - what makes it important and how to include it
- :stopwatch::bug: Using `git bisect` to find errors in history
- :mag::bug: Using a debugger
:::

:::warning
Groups:
| Room | groups |
|--- | --- |
| 1.05 | 2, 3, 7, 12, 14, 18, 20 |
| 1.21 | 4, 6, 9, 11, 13, 16, 21 |
| 4.06 | 1, 5, 8, 10, 15, 19, |
:::

:::danger
**Only use zoom if you are connecting remotely or need subtitles**
Remember to `rename` yourself by clicking on your zoom name (in the participants list) and change it to:
`SXXX` where XXX is the room number (105, 121 or 406 or 000 for the online attendees).

If you disconnect and connect again, please rename yourself again.

**Use Youtube If you are in class***
⏯ [streaming - youtube](https://youtu.be/lgWQC_nxuyM)
:::

#### What was discussed during the last 2 weeks :newspaper:
- A lot of questions about the assignment
- we won't link the points penalties in submitty with moodle.
- Groups created!
- [Forum for your group](https://moodle.ucl.ac.uk/mod/forum/view.php?id=4462882)
- Feedback survey - we will post how we are taking action to your suggestions on the forum
- UCU call to strike for next week
- [Why is it happening](https://www.ucu.org.uk/article/12469/FAQs)?
- Pensions, casualisation, equality, pay, workload
- how may it affect this course?
- 1 lesson (that lesson won't be recovered). Material will be on moodle
- It may also produced delays releasing the marks.

### Review from last lesson
- Testing and homework exercises about testing
- Documentation homework
- doctest
- sphinx
- Debugging homework
- bisect

### Groups :handshake:

Frustration with instructions (or the lack of them). Share in mentimiter a situation when you'd like better instructions.
:::info
Add your answer on [mentimiter](https://www.menti.com/altrfk1uyz3p)
:::

---
### Documentation

#### Introduction & Overview of Homework

#### Poll: Understanding Documentation

:::info
Let's have a look at what you all know about documentation already.
Go to the [voting page](https://www.menti.com/altrfk1uyz3p)!
:::

#### Exercise: Looking at Project Documentation

:::info
For this exercise you'll be looking at a single project in your groups - your task is to look at them from a usability perspective.

Consider things such as ability to understand the project's purpose, how to use it, how you might contribute to it, and where to find help if things go wrong.

In each case you'll start on the PyPI page, but do go to the source and website/documentation links:

* Groups 1 - 7: [spacy](https://pypi.org/project/spacy/)
* Groups 8 - 14: [matplotlib](https://pypi.org/project/matplotlib/)
* Groups 15+: [numpy](https://pypi.org/project/numpy/)
:::

#### Discussion of Looking at Project Documentation

In larger groups, discuss the projects you looked at. For example:
* What did you find confusing or useful?
* What were your thoughts about how the information was presented?

Choose one person from the group to add notes below about the projects and what you discussed.

- Group 1:
- ​ Natural Language Processing:helps you build applications that process and “understand” large volumes of text. It can be used to build information extraction or natural language understanding systems, or to pre-process text for deep learning.
- Group 2:use building information extraction or natural language understanding systems
- ​
- Group 3:
- Friendly with the beginners, up to date, professional, great for communicating and asking for support. Offers the chance to contribute actively. Nice interface. :D Library is commercialised
- Group 4:
- ​
- Group 5: It clearly shows that it can be used to build information extraction documentation. easy to grasp for beginners
- Group 6:
- easy for beginner to read
- Group 7:
- Fantastic documentation, great tutorials in details about specific functionalities. Nicely presented structure for navigating different topics (easy to hard).
- Group 8:
- ​ Very simple guide to get the package up and running - commands listed with a copy to clipboard button
- ​ Handouts for various ability levels and ammary cheatsheets with quick guides on various commonly used functions
- ​ Users have choice on how documetnation is presented. Either in high detail to allow complex usage or in simplified form with diagrams to succinctly project are used
- Group 9:
- ​ guidence to installation and contribution to the codes.
- Hyperlink to click for deeper understanding the matplotlib function
- Group 10:
- ​ Easy to get started with for simple graphing. Has several tutorials for different levels of eerience

- Group 11:
- ​ Presented in a clear way with several methods of installation. Different ways to contribute. If there are any problems, contact list is provided.
- ​ Including tutorials for people with no/little prior knowledge or experience with mathplotl as well as a list of different functions from the package.
- Group 12:
- ​Clear guide to quick start with tutorials and reference.
- Always a link to source code page on GitHub..
- Different builds kept totally separate.
- First pla
- Easiest bits to access are the most basic explanations -> if someone has a highlevel problem, you can trust them to find it deeper in the documentation.
- Group 13:
- ​Good visualization toll
- ​
-
- Group 14:
-- ​Regarding Matplotlib

+ Main page with an overview of the entire website's content and essential info at the front (how to install/get started)
+ Many tutorials provide examples (for beginners and more advanced users)
+ Built in search engine
+ Pristine API

- Group 15:
- ​is a powerful tool to deal with array object
- find terminology confusing
- whole document follows a good structure
- Group 16:
- ​ well laid out, lots of examples, pointers on how to augment it with other libraries
- Group 17:
- ​
- Group 18:
- ​numpy provides the different levels of guides for different users. it also provides old version's document,which is useful for a old project
- ​
- ​ Easy to read: mentions the functions that will appear in each section
- ​ Code snippets explain application well
- ​ Diagrams for ease of understanding
- Group 19:
- ​users guide is easy to understand and very useful. the way it present is simplicity and clarity,it divides a section into small parts, so user can get start easily.
- Group 20:
- ​Userful: very easy and quick to access and use the mathematical functions.
- easy to tranform other data type into numpy
- Group 21:
- ​include getting start page is very useful for the beginner
- user friendly interface, easy to navigate
- Group online:
- it was clear how to contribute using github
- Github for numpy is very informative, but it takes time to understand it
- Could be overwhelming to someone starting out with the library
- Could have just been us, but wasn't immediately obvious on how to contribute, but after searching very detailed. Full walkthrough on on how to use git
---

### Bisect

### Review the manual bisect

- [mentimenter quiz](https://www.menti.com/algi4tzbvg9z)!
- RSE-Classwork repo: [:hash::three::two:](https://github.com/UCL-COMP0233-22-23/RSE-Classwork/issues/32)

### Exercise: :brain: automate the bisect process

We will work for over 6 issues (:hash::three::four:-:hash::three::eight:), spending no more than 10' in each. Half-way through we will come all together to the main room.

:::info

Let's start!

RSE-Classwork repo: [:hash::three::four:](https://github.com/UCL-COMP0233-22-23/RSE-Classwork/issues/34) and continue through the following as you complete the tasks.

:::

---
### Debugging demo

### Next week
- Create command line programs using `Argparse`,
- How to create a python package, and
- How to make the style in your code consistent using linting tools

# Questions

:::info
Feel free to add any question below. Remember the syntax:

- Example question
  - [name=student_a] Example answer
  - [name=TA_1] Example answer

:::

- What is the difference between a getting started page and a tutorial or how-to guide?
- [name=...]
- .
- [name=...]
- .
- [name=...]

###### tags: `COMP0233` `teaching` `class`