1 Востаннє редагувалося pluszz (03.01.2021 20:05:03)

Тема: Як правильно писати документацію для додатків

Доброго часу доби всім. Оскільки не являюсь професійним програмістом, і займаюся програмування виключно як хобі, то не маю достатніх навичок в написанню документації. Хочу показати шматок української версії редмі файлу,  щоб люди котрі розуміються краще від мене оцінили чи має право на існування таке шось.

readme

...
__________________________________________________________________________________________
#Налаштування сервера, змінні середовища.

Налаштування сервера можна зберегти двома способами в змінних середовища, aбо в файлі .env.
Для налаштування додатку нееобхідно задати наступні параметри:
FLASK_APP - ім'я файлу аплікації.
SECRET_KEY - це криптографічний ключ, котрий розширення Flask-WTF використовує для
захисту веб-форм від атаки  Cross-Site Request Forgery (CSRF).
DATABASE_URL - шлях до баз данних. Якщо змінна не буде налаштована, то буде
використано шлях за замовчуванням `/app.db`.
MAIL_PORT - налаштування порту для електронної пошти за замовчуванням `25`.
MAIL_SERVER - поштовий сервер .
MAIL_USE_TLS - налаштувння протокола `TLS`.
MAIL_USERNAME - адреса поштової скриньки з котрої буде вестися розсилка.
MAIL_PASSWORD - пароль до поштової скриньки з котрої буде вестися розсилка.
FLASK_DEBUG - вмикає режим відладки додатку на тестовому сервері можна використовувати.
режим відладки для ввімкнення треба присвоїти цьому параметру значення `True` на продакшн
сервері рекомендоване значення `False`.
___________________________________________________________________________________________
##Для збереження в змінних середовища в лінукс

В терміалі:
`export <ім'я_параметра>=<значення>` (важливо перед і після знаку `=` не можна класти
знаку пробіл)
___________________________________________________________________________________________
##Для збереження в змінних середовища в віндовс

В командному рядку:
`set <ім'я_параметра>=<значення>` (важливо перед і після знаку `=` не можна класти
знаку пробіл)
___________________________________________________________________________________________
##Для збереження в файлі .env

За замовченням такого файлу немає в кореневій дерикторії, тому його треба створити
самостійно. Файл повинен виглядати наступним чином:


    SECRET_KEY = "xxxxx"
    FLASK_APP = "xxxxxx"
    MAIL_SERVER = "xxxxxx"
    MAIL_PORT = xx
    MAIL_USE_TLS = x
    MAIL_USERNAME = "xxxxxx"
    MAIL_PASSWORD = "xxxxxx"
    FLASK_DEBUG = "xxxxxx"

Після `=` повинні бути відповідні значення.
___________________________________________________________________________________________
##Захаркоджування параметрів

Крім того налаштування  можна за харкодити в файлі config.py однак цей спосіб не є рекомендованим для використання єдиний виняток, якщо середовище не визначає зміниих середовища.
___________________________________________________________________________________________
#Список поштових скриньок адміністраторів

Поштов іскринькі адміністраторів, необхідні для відправки їм повідомлень про помилки і зберігається в файлі config.py в списку `ADMINS` і змінюється шляхом його редагування.
...

Також буду вдячний за поради.
Окрім того, хотів би запитати, якщо я хочу зробити документацію на кількох мовах, краще писати її в однім файлі чи зробити кілька файлів припустимо щось таке:

  • README.md

  • UAREADME.md

  • PLREADME.md

Дякую.

Частково поправив. Дякую javascriptlife.

2

Re: Як правильно писати документацію для додатків

Здається ти жодного файла readme не прочитав. перед тим, як створити цю ... тему. таке не пишуть у файлі readme. для цього є довідка (має бути).

файл readme додають один. в ньому пишуть англійською, щоб всім було зрозуміло, що це таке. Зрідка пишуть "мовою оригінала", але то ніхто не читає.

Подякували: pluszz1

3

Re: Як правильно писати документацію для додатків

Якогось єдиного стандарту для *.md файлів я не бачив. Є тільки рекомендації:

  • Після решіток (#) має бути пробіл (для заголовків). Інакше вони не будуть заголовками.

  • Для горизонтальної лінії достатньо 3 символи підкреслення (_).

  • Стрічки, які користувач має набирати в терміналі, варто тримати в окремому рядку, щоб користувач мав можливість копіювати рядок з <Enter>.

Пропоную так:

README-uk.md
# Заголовок документа

Призначення документа, або загальний опис проекта.
___
## Налаштування сервера, змінні середовища.

Налаштування сервера можна зберегти двома способами в змінних середовища aбо в файлі `.env`.
Для налаштування додатку нееобхідно слідуючі параметри:
`FLASK_APP` - ім'я файла додатку.
`SECRET_KEY` - це криптографічний ключ котрий розширення Flask-WTF використовує його для захисту веб-форм від атаки  Cross-Site Request Forgery (CSRF).
`DATABASE_URL` - шлях до баз данних вразі якщо змінна не буде налаштована то буде використано шлях за замовчуванням `/app.db`.
`MAIL_PORT` - налаштування порта для електронної пошти за замовчуванням `25`.
`MAIL_SERVER` - поштовий сервер.
`MAIL_USE_TLS` - налаштувння протокола TLS.
`MAIL_USERNAME` - адреса поштової скриньки з котрої буде вестися розсилка.
`MAIL_PASSWORD` - пароль до поштової скриньки з корої буде вестися розсилка.
`FLASK_DEBUG` - вмикає режим відладки додатку на тестовому сервері можна використовувати.
режим відладки для ввімкнення треба присвоїти цьому параметру значення `True` на продакшн
сервері рекомендоване значення `False`.
___
### Для збереження в змінних середовища в лінукс

В терміалі:

    export <ім'я_параметра>=<значення>

(важливо перед і після знаку `=` не можна класти
знаку пробіл)
___
### Для збереження в змінних середовища в віндовс

В командному рядку:

    export <ім'я_параметра>=<значення>

(важливо перед і після знаку `=` не можна класти
знаку пробіл)
___
### Для збереження в файлі .env

За замовченням такого файлу немає в кореневій дерикторії тому його треба створити
самостійно. Файл повинен виглядати наступним чином:

    SECRET_KEY = "xxxxx"
    FLASK_APP = "xxxxxx"
    MAIL_SERVER = "xxxxxx"
    MAIL_PORT = xx
    MAIL_USE_TLS = x
    MAIL_USERNAME = "xxxxxx"
    MAIL_PASSWORD = "xxxxxx"
    FLASK_DEBUG = "xxxxxx"

Після `=` повинні бути відповідні значення.
___
### Захаркоджування параметрів

Крім того налаштування  можна за харкодити в файлі config.py однак цей спосіб не є рекомендованим для використання єдиний виняток, якщо середовище не визначає зміниих середовища.
___
## Список поштових ящиків адміністраторів

Поштові щики адміністраторів не обхідні для відправки їм повідомлень про помилки і зберігається в файлі `config.py` d списку `ADMINS` і змінюється шляхом його редагування.
...

Див. Markdown spec.

  • README.md (не мусить бути англійською, мову за замовчуванням визначає автор проекту)

  • README-uk.md

  • README-pl.md

  • README-en.md

  • README-fr.md

Подякували: bvn, pluszz, Chemist-i, ReAl4

4

Re: Як правильно писати документацію для додатків

leofun дуже дякую

5

Re: Як правильно писати документацію для додатків

ur_naz я читав цеhttps://github.com/RichardLitt/standard-readme
Вище описане належить до установки, тому що без цього мій веб додаток не буде працювати, ще планую додати про установку середовища з requirements.txt.

6

Re: Як правильно писати документацію для додатків

Є такі два правила кодування:
1. Код потрібно супроводжувати коментарями
2. Якщо код потребує коментарі, то це поганий код.

Це стосується і будь-якої документації

7 Востаннє редагувалося koala (02.01.2021 11:06:50)

Re: Як правильно писати документацію для додатків

ur_naz написав:

Є такі два правила кодування:
1. Код потрібно супроводжувати коментарями
2. Якщо код потребує коментарі, то це поганий код.

Це стосується і будь-якої документації

Це погані правила коментування. Радше так:
Тривіальний код має сам читатися як коментар, додаткових коментарів потребують лише нетривіальні місця в коді (скажімо, реалізація певного складного алгоритму), і коментарі мають відповідати на питання "навіщо", а не "що робимо".

Але документація потрібна для тих, хто не читатиме код.
Стиль readme стерпний. Зрештою, це ваш продукт, вам визначати, що там і як. По розмітці вже написали. А от мова...
додатків застосунків
зберегти двома способами: в змінних
слідуючі такі
це криптографічний ключ котрий розширення Flask-WTF використовує його для. слів треба із робити порядком щось
щики скриньки

Подякували: FakiNyan, pluszz, leofun013

8 Востаннє редагувалося pluszz (02.01.2021 12:49:46)

Re: Як правильно писати документацію для додатків

koala написав:

це криптографічний ключ котрий розширення Flask-WTF використовує його для. слів треба із робити порядком щось

Дякую, треба крапку забрати і слово "його".
Має бути

SECRET_KEY - це криптографічний ключ котрий розширення Flask-WTF використовує  для захисту веб-форм від атаки  Cross-Site Request Forgery (CSRF).

9 Востаннє редагувалося pluszz (02.01.2021 17:40:11)

Re: Як правильно писати документацію для додатків

oффтоп
Я играю в доту написав:
pluszz написав:

Крім того налаштування  можна за харкодити в файлі config.py однак цей спосіб не є рекомендованим для використання єдиний виняток, якщо середовище не визначає зміниих середовища.

Поштові щики адміністраторів не обхідні для відправки їм повідомлень про помилки і зберігається в файлі config.py d списку `ADMINS` і змінюється шляхом його редагування.

Пишете на польскій і переводите гугл перекладачем спочатку на англійську, а потім - на українську.

Пишу по українськи, але кожен день спілкуюся польською через те получаєть характерна структура речень. Я то помічав але не вважав що то аж так видно.

10 Востаннє редагувалося pluszz (02.01.2021 17:40:41)

Re: Як правильно писати документацію для додатків

оффтоп
Я играю в доту написав:

Та ні, то не видно.
А видно ваш аватар і пости на форумі - звичайний житель Польщі

Мій аватар типово буковинський пане Віталію.

11

Re: Як правильно писати документацію для додатків

Та ж кордон буковини поряд з Польщею.
Дуже чарівна, симпатична блогерка, до речі. Тільки тому я її і дивлюся, без звуку.
https://replace.org.ua/post/142249/#p142249

пане Віталію

Ви подумали що я Віталік? Я не Віталік, але форум дивлюсь досить давно, з року 14-16.

12 Востаннє редагувалося pluszz (02.01.2021 17:42:31)

Re: Як правильно писати документацію для додатків

оффтоп
Я играю в доту написав:

Та ж кордон буковини поряд з Польщею.
Дуже чарівна, симпатична блогерка, до речі. Тільки тому я її і дивлюся, без звуку.
https://replace.org.ua/post/142249/#p142249

пане Віталію

Ви подумали що я Віталік? Я не Віталік, але форум дивлюсь досить давно, з року 14-16.

Немає кордону між Буковиною та Польщею. Буковина межує з Румунією та Молдавією. Кордон з Польщею має лише Закарпаття, Львівщина та Волинь.

Подякували: 0xDADA11C7, bvn2

13

Re: Як правильно писати документацію для додатків

Буковина межує з Румунією та Молдавією.

Прихований текст

Nu ieși din subiect, dragă domn polonez.

14

Re: Як правильно писати документацію для додатків

З Молдовою, друзі, з Молдовою. Давайте вже відходити від оцих назв на совіцько-московський манер...

15 Востаннє редагувалося javascriptIsLife (03.01.2021 19:11:24)

Re: Як правильно писати документацію для додатків

offtopic
offtopic написав:

Для програм а не додатків.

16

Re: Як правильно писати документацію для додатків

Давайте всі разом вчитаємося в ці речення.

  • шлях до баз данних вразі якщо змінна не буде налаштована то буде
    використано шлях за замовчуванням `/app.db`.

  • це криптографічний ключ котрий розширення Flask-WTF використовує його для.
    захисту веб-форм від атаки  Cross-Site Request Forgery (CSRF).

  • ім'я файла додатку.

  • Налаштування сервера можна зберегти двома способами в змінних середовища aбо в файлі .env.

  • Для збереження в змінних середовища в лінукс

  • Для збереження в змінних середовища в віндовс

  • важливо перед і після знаку `=` не можна класти
    знаку пробіл

  • Захаркоджування параметрів

  • Крім того налаштування  можна за харкодити в файлі config.py однак цей спосіб не є рекомендованим для використання єдиний виняток, якщо середовище не визначає зміниих середовища.

  • Список поштових ящиків адміністраторів

  • Поштові щики адміністраторів не обхідні для відправки їм повідомлень про помилки і зберігається в файлі config.py d списку `ADMINS` і змінюється шляхом його редагування.

Дякую. Я по собі знаю що з таким потрібно звертатися до психіатра.

17

Re: Як правильно писати документацію для додатків

Слово “застосунки“ в магазині microsoft
Слово “додатки“ в Google Play - від українського “додавати“ (функціонал)
А слово “програми“ - від англійського “program“ і нічого спільного з Україною не має, але застосовується як узагальнена назва процесу створення КОМАНД керування (англ. код, code, а не кід).

18 Востаннє редагувалося pluszz (03.01.2021 19:30:12)

Re: Як правильно писати документацію для додатків

javascriptIsLife написав:

Давайте всі разом вчитаємося в ці речення.

  • шлях до баз данних вразі якщо змінна не буде налаштована то буде
    використано шлях за замовчуванням `/app.db`.

  • це криптографічний ключ котрий розширення Flask-WTF використовує його для.
    захисту веб-форм від атаки  Cross-Site Request Forgery (CSRF).

  • ім'я файла додатку.

  • Налаштування сервера можна зберегти двома способами в змінних середовища aбо в файлі .env.

  • Для збереження в змінних середовища в лінукс

  • Для збереження в змінних середовища в віндовс

  • важливо перед і після знаку `=` не можна класти
    знаку пробіл

  • Захаркоджування параметрів

  • Крім того налаштування  можна за харкодити в файлі config.py однак цей спосіб не є рекомендованим для використання єдиний виняток, якщо середовище не визначає зміниих середовища.

  • Список поштових ящиків адміністраторів

  • Поштові щики адміністраторів не обхідні для відправки їм повідомлень про помилки і зберігається в файлі config.py d списку `ADMINS` і змінюється шляхом його редагування.

Дякую. Я по собі знаю що з таким потрібно звертатися до психіатра.

Мій психічний стан відносно в нормі, моя писемна грамотність заставляє бажати кращого. Попрошу констриктивно що там не так. Буду вдячний якщо підкажете де неправильно вжита термінологія.

19

Re: Як правильно писати документацію для додатків

А знаєте де ще пишуть всілякі слова? Програма хоч і іноземне, але не таке кострубате як додаток. pluszz, знущаєтеся? Навіть якщо ні, мені лінь друкувати.

20

Re: Як правильно писати документацію для додатків

Ну, програмісти завжди намагаються все класифікувати і можуть ставити розділові знаки навіть там, де за правилами вони не потрібні. Мозок в ООП розучується правильно мислити без класифікацій.
Дуже важко читати не класифікований код (не форматований), а іще важче - не форматовану людську мову
Це тому, що команди в будь-якій мові програмування стараються зробити якомога зрозумілішими і одночасно коротшими (щоб швидше читати і набирати). А більшість слів людської мови (особливо української) дуже довгі в деякі пошано зрозумілі (особливо для тих, хто ними рідко користується).
А тут ще й вирази іншого діалекту, та без класифікації (мало розділових знаків). Це важко читати людям, які не розмовляють на вашому діалекті.
У мене родичі з Чернівців, істину кажу: так само, як plusz розмовляють і з психікою у них все добре.