Wednesday, June 23, 2021

Slave tables and delayed values

I fixed #4222, which was caused by my recent changes #4046.

I started a new topic guide about Delayed values, which also contains a test case that (probably) would have covered this issue.

A slave table can be a valid data element of a detail layout, and it is named foos.Foos (i.e. with a dot). And also the corresponding store field will be named foos.Foos (not foos_Foos), i.e. the names of store fields don’t need to be valid Python attribute names.

Diátaxis workshop

Documentation should be structured under the following four top-level entries:

• Tutorials (aka “Get started”) should be: clear, have a concise outcome, …

• How-to guides (Recipes) should be reproducible, cheat sheet

• Reference (Technical specs, description of what exists) should be correct, complete, excludes instruction and explanation, answers to facts (not the needs of the reader)

• Explanation (aka “Topics”, “Background”, “Discussion”) offer context, establishes connections, the bigger picture, history

This differs e.g. from established systems like Darwin Information Typing Architechture.

Each top-level index might be divided by “areas of usage”. Think like a shop owner: put the interesting and tempting topics at the front.

Q: Where to put the different audiences of readers? A: Consider them as being completely different manuals. E.g. end users, developers, contributors, training providers, hosters… one manual for each of them