Насоки към авторите
Авторите на книгите от поредицата "Programming Basics" (Основи на програмирането) се съгласяват да следват настоящите насоки, за да се уеднакви стилът на писане.
Целта на книгите е да се ползват като учебник за курсовете "Programming Basics" в СофтУни.
-
Следваме слайдовете от курса "Programming Basics" в СофтУни: https://github.com/SoftUni/Programming-Basics-Resources/tree/master/Python-Course-SoftUni.
-
Можем да добавяме и допълнителна информация, не сме 100% вързани за слайдовете.
-
Ползваме GitBook платформата, защото тя е много подходяща за open-source книги: https://python-book.softuni.bg.
-
Лицензът е CC-BY-NC-SA.
Стараем се да форматираме кода качествено, да слагаме заглавията в добра йерархия (H1, H2, H3) и да слагаме bold за ключови фрази от всеки абзац, за да улесним четенето на текста и навигирането в него с поглед.
Ползваме Markdown форматиране в GitBook платформата. Където не става с Markdown, слагаме HTML (примерно за входа и изхода в условията на задачите).
Всички елементи от кода (имена на променливи, keywords, имена на файлове и подобни) форматираме като код ограден ляв апостроф. Пример:
В Python можем да повтаряме команди с
forцикъл. Операторътforповтаря група команди няколко пъти.
Python кодът се форматира по стандартния за markdown езика начин, като езикът е "python". Пример:
for x in range(1, 100):
print(x)Често пъти при подсказките към задачите искаме да дадем screenshot с кода вместо самия код, за да избегнем възможността за copy / paste. В тези случаи трябва да се взима screenshot от PyCharm (със светла тема), за да е оцветен правилно кода. Ето добър пример:
Понякога нарочно замъгляваме част от кода, за да накараме читателят да мисли, вместо да преписва на сляпо кода:
Примерните вход и изход при задачите за упражнения се форматират като в примера по-долу с използване на HTML тагове и по-конкретно <br> за слизане на нов ред. Ето пример:
| Вход | Изход | Вход | Изход | Вход | Изход |
|---|---|---|---|---|---|
| 2 10 20 |
30 | 3 -10 -20 -30 |
-60 | 4 45 -20 7 11 |
43 |
- Правим картинките като
PNGи се стараем да са с добър контраст. - Размерът (width) да НЕ Е по-голям от 640px.
- Да не се ползва JPG, защото чупи качеството на изображението.
- Резолюцията (DPI) трябва винаги да е 96:
- При картинки с код - големината на шрифта трябва да е като този на картинката по-долу (не е използван zoom, но при различните устройства може да е друго число).
- Темата на PyCharm e светлата. ("IntelliJ")
- Размера на шрифта в PyCharm e 13, Monospaced (при различните устройства може да е различен). Вижте как да промените настройките в записки от учредителната среща.
- Картинките се организират в папка assets, като всяка глава си има своя папка. Обръщаме внимание на именуването на картинките - нека в заглавието присъства информация за номера и името на задачата или примера, за които е използвана картинката, както и поредността й. Пример за добро именуване на файл:
13.Fibonacci-01.png.
Пример:
Когато взимаме картинки от слайдовете, се стараем да ползваме цветовете от PPTX шаблона за картинки. Трябва да се получи нещо такова:
Пишем в множествено число. Пример:
Да разгледаме кода на примерната програма. На първия ред забелязваме .... Тя служи за ...
Заглавията следват структурата на слайдовете. Слагайте повече подзаглавия, за да е по-хубаво структуриран текстът.
- Heading 1 - заглавие на глава от книгата
- Heading 2 - заглавие на секция от дадена глава
- Heading 3 - заглавие на под-секция от дадена глава
Важни забележки, на които искаме да обърнем специално внимание, се правят със следния HTML код:
<table><tr><td><img src="/assets/alert-icon.png" style="max-width:50px" /></td>
<td>Тази книга ви дава само <b>първите стъпки към програмирането</b>. Тя обхваща
съвсем начални умения, които предстои да развивате години наред докато достигнете
до ниво, достатъчно за започване на работа като програмист.</td>
</tr></table>Резултатът е нещо такова:
Не променяйте HTML кода. Той е внимателно написан, за да се визуализира коректно на лаптоп, таблет, телефон и като PDF).
Можем да вмъкваме YouTube видео клипчета в книгата със следния HTML код:
<div class="video-player">
Гледайте видео-урок по тази глава тук: <a target="_blank"
href="https://www.youtube.com/watch?v=LgT10WCBw0M">
https://www.youtube.com/watch?v=LgT10WCBw0M</a>.
</div>
<script src="/assets/js/video.js"></script>Горният код ползва малко JavaScript, който се изпълнява в GitBook при рендиране на книгата в HTML формат. В GitHub не се изпълнява, както и при PDF рендиране. Така в PDF се показва текст в стил "гледайте видео тука + link", а при HTML формат на книгата, се появява YouTube video player с page width (responsive) размери (width: 100%, height: изчислява се по формат 16/9). При преглеждане на страницата с GitHub markdown viewer, се появява линк към видеото.
| Вход | Изход |
|---|---|
| 3 |
$ $$$$$
|
За примерните задачи и задачите за упражнение, в заглавията да се ползва Heading 3 и винаги да се изписва по следния начин:
- Задача: <наименование> или
- Пример: <наименование>
Пример:
###Задача: числата от N до 1 в обратен ред
###Пример: числата от N до 1 в обратен ред
Секциите на самата задача, като 'вход', 'изход', 'насоки и подсказки', 'тестване в Judge системата', форматираме с H4. Пример:
####Тестване в Judge системата
Тествайте решението си тук: https://judge.softuni.bg/Contests/Practice/Index/514#11
Тествайте решението си тук: https://judge.softuni.bg/Contests/Practice/Index/514#11
Форматирането на ключови фрази, понятия, думи в текста се правят bold. Това подобрява четимостта на текста.
Пример:
Сега ще напишем логиката по пресмятане на броя тухли на ред, която ще използваме след това, за да изчертаем тухлите. -> Сега ще напишем логиката по пресмятане на броя тухли на ред, която ще използваме след това, за да изчертаем тухлите.
**пресмятане на броя тухли на ред**Където предстои промяна, слагайте маркер [TODO], примерно [TODO: update judge link]. Ще ползваме TODO маркер за моменти, които не можем да поправим на момента или са обект на дискусия. Засега просто ги отбелязвайте.
Пример:
[TODO: update judge link]Ако използваме TODO маркер в някой от скрийншотите, коректният начин на изписване е следния:
// TODO: ...
За всички теми: да се тества какво става на таблет / телефон и да се измисли как да се адаптира съдържанието. Най-честият източник на проблеми за responsive design са таблиците. Избягвайте много колони в таблиците. Повечето могат да се направят на няколко отделни таблици с по-малко колони. Знам, че в оригиналните MS Wоrd файлове ползваме много колони, за да спестим място. Обаче тази книга трябва да е четима от телефон и по-добре да помислим за това. След тестване установихме, че е по-добре да се ползва markdown
Пример:
| Вход | Изход | Вход | Изход | Вход | Изход |
|---|---|---|---|---|---|
| 2 10 20 |
30 | 3 -10 -20 -30 |
-60 | 4 45 -20 7 11 |
43 |
| Вход | Изход | Вход | Изход | Вход | Изход |
| :--- | :--- | :--- | :--- | :--- | :--- |
| 2<br>10<br>20 | 30 | 3<br>-10<br>-20<br>-30 | -60 | 4<br>45<br>-20<br>7<br>11<br> | 43 |Когато имаме име на функция в текста, ползваме () или (…), за да улесним читателя. Примерно math.trunc -> math.trunc(…). Първото изглежда като property. Второто е очевидно, че е функция / метод, защото има някакви параметри в скобите.
Пример:
Math.Truncate(…)След предлог в българския език винаги следва кратък член. Грешно:
"на последният ред".
Вярно:
"на последния ред".
Пълен член се слага, ако фразата отговоря на въпроса "кой"? Пример
"операторът == сравнява две стойности".
Въпрос: кой? Отговор: "операторът ==".
Кратък член се слага, ако фразата отговаря на въпроса "кого?". Пример:
"чертане на първия стълб" -> "на кого?" -> кратък член.
Целият код, примери и напътствия да следват официалния Python coding standard: PEP 8
Заглавията в български език са в стил "Главна буква, следвана от само малки". Коректен пример:
"Входна единица".
Некоректен пример:
"Входна Единица".
Заглавията, които съдържат въпрос, трябва да завършват на "?", примерно това е грешно заглавие:
"Какво представлява while цикълa".
Това е правилно заглавие:
"Какво представлява while цикълът?"
И трябва да е с пълен член, защото отговаря на въпроса "кой?"
В / във и с / със. В български език се ползва предлог "във" единствено, когато следващата дума започва с буквата "в". Аналогично "със" се ползва, когато следващата дума след предлога започва с буквата "с". Коректен пример:
"на входа се подават x1, y1, x2, y2, x3, y3 в този си ред".
Грешен пример:
"на входа се подават x1, y1, x2, y2, x3, y3 във този си ред".