[NTG-context] Re: your opinion about list structures

[Keith McKay <mckaymeister@gmail.com>]

Hi Hraban

Here are my thoughts on your ConTeXt Book.

[TOC] Definitely only show Chapters and Appendices. A list of sections 
could go under the Chapter Title, it would more useful there. I don't 
think there is also a need include sub-sections, (if you have them) it 
could make the list inordinately long.

[Registers] My own preference would be a command and a topic index if 
only for convenience sake.

[Glossary] I don't think an index of abbreviations is necessary if they 
are already in the index.

[Other Lists] I don't think a list of colours is necessary, you could 
just point them to the wiki.

Just my thoughts, and I look forward to read the English version of your 
book. (smiling)

Best Wishes

Keith McKay

p.s. It's been so long since I worked with technical books that I would 
have to blow the dust off them.

On 10/08/2023 14:21, Henning Hraban Ramm wrote:
> Hi, this is about my ConTeXt book again…
>
> [ToC]
>
> At the moment, my table of contents has chapters and sections and is 8 
> pages long. I would probably hardly use it.
>
> Maybe it would be better to show only chapters (29 content + 12 
> appendix = 2 pages) and include a list of sections after the chapter 
> title (or not at all).
>
> [Registers]
>
> I split between command and topic index (9 pages each), because I find 
> it annoying to have the commands between the topics.
> I also include the topics that are mentioned in titles in the index, 
> because I hate it if I must look in two places.
> (Otherwise I wouldn’t think about omitting the sections from the ToC.)
>
> At the moment there‘s also an index of todo items, but that will 
> disappear before print.
>
> [Glossary]
>
> There’s a short dictionary of technical terms in the appendix (8.5 
> p.). Each lemma is also included in the index.
>
> Should I add a list of abbreviations? (TDS, TEI, OCG, RAL, PDF, SVG…?)
> They’re in the index and explained where they matter – I don’t think 
> the meaning of many abbreviations like file types is important.
>
> [Other lists]
>
> Should I include a list of colors, like the output of 
> \showcolor[crayola]? (I think it would only bloat the book, and 
> everyone can create the list themselves.)
>
> I have lists of supported languages (should get checked), fonts in the 
> distribution and all math fonts, because these are not easily 
> reproducible (AFAIK).
>
>
> So, what do you think, and how do you like to work with technical books?
> What kind of information (about ConTeXt or documents/printing in 
> general) do you find hard to find?
>
> Hraban
> ___________________________________________________________________________________ 
>
> If your question is of interest to others as well, please add an entry 
> to the Wiki!
>
> maillist : ntg-context@ntg.nl / 
> https://www.ntg.nl/mailman/listinfo/ntg-context
> webpage  : https://www.pragma-ade.nl / http://context.aanhet.net
> archive  : https://bitbucket.org/phg/context-mirror/commits/
> wiki     : https://contextgarden.net
> ___________________________________________________________________________________
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : https://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : https://contextgarden.net
___________________________________________________________________________________