Improve clarity and usability of README for first-time Howitz users #86

podliashanyk · 2024-03-22T09:41:49Z

Improvements stem mostly from the user test on @stveit where he was setting up Howitz to run for the first time by following the docs in the README.

Closes #93

Otherwise pip might complain about several directories having the same name: howitz venv dir and howitz module dir

Makes it easier to see this info and use it. Also marks this info clearly as an optional one

User testing showed that this info wasn't apparent enough for a new user

Don't assume user has read the run in dev section before reading this section

There was confusion for a first-timer about what this value should be because of "tld"

It shows how to configure alternative connections, yet doesnt require any action for new users when they copy values from the example config file to the actual config file

codecov-commenter · 2024-03-22T09:42:50Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Please upload report for BASE (main@b07d8c9). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #86   +/-   ##
=======================================
  Coverage        ?   48.98%           
=======================================
  Files           ?       15           
  Lines           ?      835           
  Branches        ?        0           
=======================================
  Hits            ?      409           
  Misses          ?      426           
  Partials        ?        0

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

github-actions · 2024-03-22T09:42:59Z

Test results

  4 files   4 suites 8s ⏱️
14 tests 14 ✔️ 0 💤 0 ❌
56 runs 56 ✔️ 0 💤 0 ❌

Results for commit 5a5b366.

♻️ This comment has been updated with latest results.

johannaengland

Set up worked quite smoothly, no complaints there.

I will add some commits containing small typo/article/formulation fixes.

README.rst

podliashanyk · 2024-05-22T09:11:53Z

One nitpick (other than my inline ones): I saw several references to the configuring the backend "Zino 1" server. I don't think we should specify which version of Zino to connect to, all the while we are developing a compatible version 2 of Zino.

Created a separate issue for this #91

hmpf · 2024-05-30T06:02:39Z

README.rst

+    The easiest way to configure Howitz is via a ``toml`` file.
+
+    1. Create an empty ``.howitz.toml`` file in the project root folder.
+    2. Copy the values from the example config file ``dev-howitz.toml`` to ``.howitz.toml``.


I haven't found a good way to mute the logging that happens on startup unfortunately. Maybe we should ship a default logging config that does that, or use a flag to explicitly turn it on.

hmpf · 2024-05-30T06:21:15Z

README.rst


-There's a handler "debug" that will copy everything DEBUG or higher to a file
+There's a handler ``debug`` that will copy everything DEBUG or higher to a file


Better: "As for logging, there is a handler"..

hmpf · 2024-05-30T06:23:36Z

dev-howitz.toml

+level = "ERROR"
+
+## Comment out and tweak in order to configure logging level for dev or prod
+#[logging.formatters.default]
+#format = "%(levelname)s %(name)s in %(funcName)s: %(message)s"
+#


With this, the config file is suitable neither for development nor production without major alterations. I'm not sure this is a good idea. @lunkwill42?

If we want a clean separation, the example config file referenced in the README should not be a file called dev-howitz.toml. howitz.toml.example could do - then we could keep a howitz.dev.toml.example or something. Normal folks do not want to start with the latter file, @hmpf @podliashanyk

I like the idea with multiple example files!

Added howitz.min.toml.example and howitz.dev.toml.example and updated the docs.
Is there a need to provide an additional example file for prod? Or do we just rename the dev one to howitz.toml.example? @hmpf @lunkwill42

I took a closer look at the "Configuration"-section in the README. It describes the differences between dev config and prod config, and mentions the example file. So I landed on having a universal extended howitz.toml.example and a minimal howitz.min.toml.example.
Updated the README accordingly.

lunkwill42

Everything looks a lot better now - but we need a decision on multiple example config files. We want to satisfy devs without confusing regular users...

lunkwill42 · 2024-05-31T08:58:09Z

dev-howitz.toml

+level = "ERROR"
+
+## Comment out and tweak in order to configure logging level for dev or prod
+#[logging.formatters.default]
+#format = "%(levelname)s %(name)s in %(funcName)s: %(message)s"
+#


If we want a clean separation, the example config file referenced in the README should not be a file called dev-howitz.toml. howitz.toml.example could do - then we could keep a howitz.dev.toml.example or something. Normal folks do not want to start with the latter file, @hmpf @podliashanyk

hmpf · 2024-06-03T08:01:26Z

howitz.dev.toml.example


 [logging]
 version = 1

 [logging.root]
-level = "DEBUG"
+level = "ERROR"


Let this one go back to debug since it is for developers.

hmpf · 2024-06-03T08:04:37Z

howitz.min.toml.example

I would add this:

[logging.formatters.default] format = "%(levelname)s %(name)s in %(funcName)s: %(message)s" [logging.handlers.null] class = "logging.NullHandler" [logging.handlers.wsgi] class = "logging.StreamHandler" stream = "ext://flask.logging.wsgi_errors_stream" formatter = "default"

They are not used unless the [logging.loggers.MODULE]-stuff is also included.

This seems to clutter the minimal file. Don't really see the reason to include it especially since it will not be activated unless [logging.loggers.MODULE]-stuff is included.

Since this section is mostly filled with general and universal info about the the values in the toml config file

lunkwill42 · 2024-06-06T10:55:16Z

howitz.min.toml.example

+
+[howitz]
+storage = "./howitz.sqlite3"
+devmode = true


What's devmode do? Doesn't sound very production-y to me...

devmode is primarily used for flask app configuration. Values for flask server address and flask storage location will have reasonable dev defaults if devmode is True and are empty otherwise. @hmpf are there any other use cases for devmode in Howitz?

Good point, it shouldn't be set to true in example config without additional changes! Will fix.

We tried adding a cli-flag devmode to make it very explicit when running for development: debug is set to True as well as some other things. But we stopped trying to support it as a cli-flag and now keep it only in the config-file because making it work with flask --app howitz run was proving too hard/not worth the effort.

Have added warnings in the README about checking out the "Config file for production"-section when configuring Howitz for prod.
But I have a mild suspicion that the mentioned "Config file for production"-section is somewhat incomplete. Have created #109

lunkwill42

Fine by me - if my assumption about refresh intervals hold true - otherwise, 5 would be a bad default 😆

lunkwill42 · 2024-06-06T13:55:55Z

README.rst

+The refresh interval for the events table can be changed by adding for example ``refresh_interval = 10`` to
+the ``[howitz]``-section or setting the environment variable ``HOWITZ_REFRESH_INTERVAL`` to a new value.
+Refresh interval values are in seconds and must be integers. The default value is ``5`` seconds.


Question: After the NTIE PR was merged, I hope refresh interval refers to often HTMX is set to poll the Howitz backend for NTIE updates, not to an interval of full table refreshes?

Thats right, it refers to the interval for NTIE updates! NTIE PR is already merged #87 so there is no more interval (or code for that matter) for full table refreshes in Howitz anymore. 😌

The naming refresh/poll is still confusing unfortunately. We decided to use word poll for "poll router or interface"-feature, and word refresh for "poll Zino server for NTIE updates"-feature.
I will add a sentence with clarification on it in the README. 🙃

README.rst

podliashanyk added 10 commits March 21, 2024 15:55

Rename howitz venv

80f5413

Otherwise pip might complain about several directories having the same name: howitz venv dir and howitz module dir

Format zinolib setup for dev as a tip

1044407

Makes it easier to see this info and use it. Also marks this info clearly as an optional one

Highlight info about existence of example config file

64f773f

User testing showed that this info wasn't apparent enough for a new user

Make run in dev-mode section more Howitz first-timer friendly

81b3489

Add info about configuration to the run in prod section

bba85db

Don't assume user has read the run in dev section before reading this section

Remove confusion about what is tld

ac9f5f1

There was confusion for a first-timer about what this value should be because of "tld"

Polish in configuration section

a3566da

Add section explaining howitz db values

75af5a2

Set poll interval to 60s in example dev config file

6bcf615

Comment out alternative zino profiles section in example config

86af3b1

It shows how to configure alternative connections, yet doesnt require any action for new users when they copy values from the example config file to the actual config file

podliashanyk self-assigned this Mar 22, 2024

podliashanyk added documentation Improvements or additions to documentation beta Part of beta release usability testing Needs or is a part of UX testing labels Mar 22, 2024

podliashanyk marked this pull request as ready for review March 22, 2024 10:00

podliashanyk requested review from lunkwill42, hmpf, stveit and johannaengland March 22, 2024 10:00

Add step-by-step section about running Howitz

53c29c7

podliashanyk force-pushed the improve-setup-docs branch from b13edcf to 53c29c7 Compare March 22, 2024 10:05

johannaengland requested changes Apr 4, 2024

View reviewed changes

README.rst Outdated Show resolved Hide resolved

johannaengland added 5 commits April 4, 2024 15:38

Change label of url

c1fd048

Adding articles, changing prepositions

0de11d2

Change phrasing

c492252

Change capitalization

ee5af75

Change formatting

2c7366b

podliashanyk requested a review from johannaengland April 4, 2024 14:02

podliashanyk requested review from johannaengland and lunkwill42 May 22, 2024 09:12

hmpf reviewed May 30, 2024

View reviewed changes

Polish wording

b3f8ad9

lunkwill42 requested changes May 31, 2024

View reviewed changes

podliashanyk force-pushed the improve-setup-docs branch from 172c1e1 to c87e965 Compare May 31, 2024 14:38

Add minimal and dev toml-config example files

7692e0a

podliashanyk force-pushed the improve-setup-docs branch from c87e965 to 7692e0a Compare May 31, 2024 14:46

hmpf reviewed Jun 3, 2024

View reviewed changes

podliashanyk added 3 commits June 3, 2024 11:29

Give a more universal name to an extended example config file

6188a8e

Give a more appropriate name to section about dev config file

b5211da

Since this section is mostly filled with general and universal info about the the values in the toml config file

Set root log level to DEBUG in extended example config file

2b2089c

podliashanyk requested review from hmpf and lunkwill42 June 3, 2024 11:29

lunkwill42 approved these changes Jun 6, 2024

View reviewed changes

podliashanyk added 4 commits June 6, 2024 15:04

Fix typo

acbc9f6

Remind to set devmode to false when configuring for prod

49d0588

Remind to check out configuring for production section

cede3c9

Merge branch 'main' into improve-setup-docs

bc9f999

podliashanyk requested a review from lunkwill42 June 6, 2024 13:48

lunkwill42 approved these changes Jun 6, 2024

View reviewed changes

Clarify the purpose of the refresh_interval value

bcbcf69

podliashanyk changed the title ~~Add more user docs about running Howitz for the first time~~ Improve clarity and usability of README for first-time Howitz users Jun 6, 2024

lunkwill42 reviewed Jun 7, 2024

View reviewed changes

README.rst Outdated Show resolved Hide resolved

Attempt to describe refresh interval val without architecture details

5a5b366

podliashanyk requested a review from lunkwill42 June 7, 2024 08:44

lunkwill42 approved these changes Jun 7, 2024

View reviewed changes

podliashanyk merged commit 0f25da1 into main Jun 7, 2024
5 checks passed

podliashanyk deleted the improve-setup-docs branch June 7, 2024 11:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve clarity and usability of README for first-time Howitz users #86

Improve clarity and usability of README for first-time Howitz users #86

podliashanyk commented Mar 22, 2024 •

edited

Loading

codecov-commenter commented Mar 22, 2024 •

edited

Loading

github-actions bot commented Mar 22, 2024 •

edited

Loading

johannaengland left a comment

podliashanyk commented May 22, 2024

hmpf May 30, 2024

hmpf May 30, 2024

hmpf May 30, 2024

lunkwill42 May 31, 2024

podliashanyk May 31, 2024

podliashanyk May 31, 2024

podliashanyk Jun 3, 2024

lunkwill42 left a comment

lunkwill42 May 31, 2024

hmpf Jun 3, 2024

hmpf Jun 3, 2024

podliashanyk Jun 3, 2024

lunkwill42 Jun 6, 2024

podliashanyk Jun 6, 2024 •

edited

Loading

hmpf Jun 6, 2024

podliashanyk Jun 6, 2024

lunkwill42 left a comment

lunkwill42 Jun 6, 2024

podliashanyk Jun 6, 2024 •

edited

Loading

podliashanyk Jun 6, 2024 •

edited

Loading


		There's a handler "debug" that will copy everything DEBUG or higher to a file
		There's a handler ``debug`` that will copy everything DEBUG or higher to a file

Improve clarity and usability of README for first-time Howitz users #86

Improve clarity and usability of README for first-time Howitz users #86

Conversation

podliashanyk commented Mar 22, 2024 • edited Loading

codecov-commenter commented Mar 22, 2024 • edited Loading

Codecov Report

github-actions bot commented Mar 22, 2024 • edited Loading

Test results

johannaengland left a comment

Choose a reason for hiding this comment

podliashanyk commented May 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lunkwill42 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

podliashanyk Jun 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lunkwill42 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

podliashanyk Jun 6, 2024 • edited Loading

Choose a reason for hiding this comment

podliashanyk Jun 6, 2024 • edited Loading

Choose a reason for hiding this comment

podliashanyk commented Mar 22, 2024 •

edited

Loading

codecov-commenter commented Mar 22, 2024 •

edited

Loading

github-actions bot commented Mar 22, 2024 •

edited

Loading

podliashanyk Jun 6, 2024 •

edited

Loading

podliashanyk Jun 6, 2024 •

edited

Loading

podliashanyk Jun 6, 2024 •

edited

Loading