Wiki - test/proposal to further clarify documentation - ntg-context

newer
build_parshape and \getshapetext -...

Wiki - test/proposal to further clarify documentation

garulfo＠azules.eu

14 Apr 2024 14 Apr '24

5:21 a.m.

Hi all, I just discover the Diátaxis documentation framework : - https://www.diataxis.fr/ - 30min video : "What nobody tells you about documentation", https://www.youtube.com/watch?v=t4vKPhjcMZg , from Daniele Procida at PyCon 2017 As I understand it, it can help both readers and writers of the documentation by clarifying the purpose of each element. So I started a potential new "welcome page" : https://wiki.contextgarden.net/Main_Page2 The main lines would be : - Tutorials: installation pages, step by step examples - How-to guides: most of the existing wiki pages which are not https://wiki.contextgarden.net/Commands/ ... - Discussions and manuals: most of the existing manuals - Reference : the pages dedicated to commands which already include link to mailing list, stack exchange, ConTeXt's source - https://wiki.contextgarden.net/Category:Commands - https://wiki.contextgarden.net/Special:PrefixIndex?prefix=Command%2F To match the logic of Diátaxis, maybe some material from command pages should be moved from "Reference" to "How-to guides", for example, when the examples go beyond "pure description" and begin to deal with "how-to" cases, e.g. : - Reference for setuphead: https://wiki.contextgarden.net/Command/setuphead - How-to guides for headings: https://wiki.contextgarden.net/Titles If it make sense, and according to your feedbacks, I can continue to reallocate existing contents. Thanks for your feedback and thoughts. Garulfo

Show replies by date

Henning Hraban Ramm

14 Apr 14 Apr

8:14 a.m.

Hi Garulfo, I’m not against the “new order”, but I’d keep the colorful subject tiles. Different accesses are good IMO (as long as it doesn’t get to convoluted). I’d say updating, sorting, restructuring pages is more important than a new start page. Yes, please sort out reference vs. tutorials! Often examples make sense in the reference pages, so the distinction is a bit fuzzy, but there are enough where a subject/tutorial page would make more sense than examples spread over several single command pages. We could also define if the “main” reference page (with examples) is \definestuff, \setupstuff, or \stuff – IMO \setupstuff makes the most sense, since usually the others inherit from it. Often enough, parameters aren’t explained in the reference pages; sometimes you can find examples using them, but there are too many holes. I tried to fix that where I could, but too often I don’t understand enough of the sources to make sense of some setting. For wiki contributors, it might make sense to combine the markup pages – in many pages e.g. <texcode> is used where <context src="yes"> would make more sense; often \starttext … \stoptext is not necessary and just blows up examples; markup is generally somewhat chaotic (e.g. <tt>, <code>, or ``?). Hraban Am 14.04.24 um 13:21 schrieb garulfo@azules.eu:

...

I just discover the Diátaxis documentation framework : - https://www.diataxis.fr/ - 30min video : "What nobody tells you about documentation", https://www.youtube.com/watch?v=t4vKPhjcMZg , from Daniele Procida at PyCon 2017

As I understand it, it can help both readers and writers of the documentation by clarifying the purpose of each element.

So I started a potential new "welcome page" : https://wiki.contextgarden.net/Main_Page2

The main lines would be : - Tutorials: installation pages, step by step examples - How-to guides: most of the existing wiki pages which are not https://wiki.contextgarden.net/Commands/ ... - Discussions and manuals: most of the existing manuals - Reference : the pages dedicated to commands which already include link to mailing list, stack exchange, ConTeXt's source - https://wiki.contextgarden.net/Category:Commands - https://wiki.contextgarden.net/Special:PrefixIndex?prefix=Command%2F

To match the logic of Diátaxis, maybe some material from command pages should be moved from "Reference" to "How-to guides", for example, when the examples go beyond "pure description" and begin to deal with "how-to" cases, e.g. : - Reference for setuphead: https://wiki.contextgarden.net/Command/setuphead - How-to guides for headings: https://wiki.contextgarden.net/Titles

If it make sense, and according to your feedbacks, I can continue to reallocate existing contents.

Thanks for your feedback and thoughts. Garulfo ___________________________________________________________________________________ If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl webpage : https://www.pragma-ade.nl / https://context.aanhet.net (mirror) archive : https://github.com/contextgarden/context wiki : https://wiki.contextgarden.net ___________________________________________________________________________________

Peter Hopcroft

1:45 p.m.

It would be great if the main page actually said what Context does.

...

On 15/04/2024, at 2:18 AM, Henning Hraban Ramm wrote:

Hi Garulfo,

I’m not against the “new order”, but I’d keep the colorful subject tiles. Different accesses are good IMO (as long as it doesn’t get to convoluted).

I’d say updating, sorting, restructuring pages is more important than a new start page.

Yes, please sort out reference vs. tutorials!

Often examples make sense in the reference pages, so the distinction is a bit fuzzy, but there are enough where a subject/tutorial page would make more sense than examples spread over several single command pages.

We could also define if the “main” reference page (with examples) is \definestuff, \setupstuff, or \stuff – IMO \setupstuff makes the most sense, since usually the others inherit from it.

Often enough, parameters aren’t explained in the reference pages; sometimes you can find examples using them, but there are too many holes. I tried to fix that where I could, but too often I don’t understand enough of the sources to make sense of some setting.

For wiki contributors, it might make sense to combine the markup pages – in many pages e.g. <texcode> is used where <context src="yes"> would make more sense; often \starttext … \stoptext is not necessary and just blows up examples; markup is generally somewhat chaotic (e.g. <tt>, <code>, or ``?).

Hraban

...
Am 14.04.24 um 13:21 schrieb garulfo@azules.eu: I just discover the Diátaxis documentation framework : - https://www.diataxis.fr/ - 30min video : "What nobody tells you about documentation", https://www.youtube.com/watch?v=t4vKPhjcMZg , from Daniele Procida at PyCon 2017 As I understand it, it can help both readers and writers of the documentation by clarifying the purpose of each element. So I started a potential new "welcome page" : https://wiki.contextgarden.net/Main_Page2 The main lines would be : - Tutorials: installation pages, step by step examples - How-to guides: most of the existing wiki pages which are not https://wiki.contextgarden.net/Commands/ ... - Discussions and manuals: most of the existing manuals - Reference : the pages dedicated to commands which already include link to mailing list, stack exchange, ConTeXt's source - https://wiki.contextgarden.net/Category:Commands - https://wiki.contextgarden.net/Special:PrefixIndex?prefix=Command%2F To match the logic of Diátaxis, maybe some material from command pages should be moved from "Reference" to "How-to guides", for example, when the examples go beyond "pure description" and begin to deal with "how-to" cases, e.g. : - Reference for setuphead: https://wiki.contextgarden.net/Command/setuphead - How-to guides for headings: https://wiki.contextgarden.net/Titles If it make sense, and according to your feedbacks, I can continue to reallocate existing contents. Thanks for your feedback and thoughts. Garulfo ___________________________________________________________________________________ If your question is of interest to others as well, please add an entry to the Wiki! maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl webpage : https://www.pragma-ade.nl / https://context.aanhet.net (mirror) archive : https://github.com/contextgarden/context wiki : https://wiki.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://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl webpage : https://www.pragma-ade.nl / https://context.aanhet.net (mirror) archive : https://github.com/contextgarden/context wiki : https://wiki.contextgarden.net ___________________________________________________________________________________

Henning Hraban Ramm

16 Apr 16 Apr

1:07 p.m.

Am 14.04.24 um 21:45 schrieb Peter Hopcroft via ntg-context:

...

It would be great if the main page actually said what Context does.

In my poster (still WIP) I wrote: start --- The “infamous” alternative to LaTeX While most designers use graphical tools, there are still areas where code-based typesetting systems are fun, make sense or are even superior. While LaTeX is the most known of these, ConTeXt is used by a growing minority of ambitioned enthusiasts around the world. The small but active and creative community of ConTeXt users and developers is always driving TeX development over new frontiers: NTS, MetaFun, Oriental TeX, LuaTeX, mplib, LuaMetaTeX… They’re also dubbed the incisors (AKA cutting edge) of the dinosaur of Open Source. ConTeXt is aimed at creative users, known for advanced features like extensive font control and direct XML processing, with a deep integration of Lua and MetaPost. --- ConTeXt was invented in the 1990s by Hans Hagen and Ton Otten of the Dutch company “Pragma Advanced Document Engineering” for typesetting schoolbooks. Taco Hoekwater refactored the TeX source code to create LuaTeX which was further developed into LuaMetaTeX by Hans Hagen (and lately Mikael Sundqvist for refined math typography). --- “To be fair, switching to the ConTeXt way of thinking and doing things was not an overnight process […]. But once I got used to it, I could not imagine going back to LaTeX. I’ll go even further and say that, in my view, ConTeXt is the future of TeX. (Prof. Idris Samawi Hamid, 2009) Source: www.tug.org/interviews/hamid.html --- “ConTeXt is LaTeX done right. It is simple, flexible and powerful.” (J. U. Hasecke on Mastodon, 2022) --- Is ConTeXt for me? If you want … * to design your own layout * best quality math typesetting * to use Lua functions e.g. for processing data * deep integration of a graphics language (MetaPost) * to process XML input * no package conflicts * to use OpenType features * consistent setup commands * to place stuff on layers * visual debugging features * to have a lean, but mighty TeX system * to typeset much faster than with LaTeX * high quality Arabic typography … then ConTeXt is for you! --- stop

Peter Hopcroft

1:56 p.m.

...

On 17/04/2024, at 7:11 AM, Henning Hraban Ramm wrote:

In my poster (still WIP) I wrote: …

Excellent

Thomas A. Schmitz

17 Apr 17 Apr

12:32 a.m.

...

On 16. Apr 2024, at 21:56, Peter Hopcroft via ntg-context wrote:

...
On 17/04/2024, at 7:11 AM, Henning Hraban Ramm wrote:

In my poster (still WIP) I wrote: …

Excellent

No, I must admit I don’t like the first two paragraphs. The question is “what is ConTeXt,” and the answer is “we’re not LaTeX.” And why “infamous”? Thomas

Hans Hagen

2:36 a.m.

On 4/17/2024 8:32 AM, Thomas A. Schmitz wrote:

...

...
On 16. Apr 2024, at 21:56, Peter Hopcroft via ntg-context wrote:

...
On 17/04/2024, at 7:11 AM, Henning Hraban Ramm wrote:

In my poster (still WIP) I wrote: …

Excellent

No, I must admit I don’t like the first two paragraphs. The question is “what is ConTeXt,” and the answer is “we’re not LaTeX.” And why “infamous”?

I agree. It sounds the same as "we're not msword" or "we're not google docs". (In the end the only thing that latex and context have in common is that they use the tex language / ecosystem.) Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl -----------------------------------------------------------------

Henning Hraban Ramm

2:47 a.m.

Am 17.04.24 um 10:36 schrieb Hans Hagen:

...

On 4/17/2024 8:32 AM, Thomas A. Schmitz wrote:

...
...
On 16. Apr 2024, at 21:56, Peter Hopcroft via ntg-context wrote:

...
On 17/04/2024, at 7:11 AM, Henning Hraban Ramm wrote:

In my poster (still WIP) I wrote: …

Excellent

No, I must admit I don’t like the first two paragraphs. The question is “what is ConTeXt,” and the answer is “we’re not LaTeX.” And why “infamous”?

I agree. It sounds the same as "we're not msword" or "we're not google docs". (In the end the only thing that latex and context have in common is that they use the tex language / ecosystem.)

In my experience, most people interested in ConTeXt know LaTeX, so it makes sense to compare. And I actually just say “LaTeX is the most known command-based typesetting system” (that’s just true) to shortcut explaining what a cbts might be. Your critique applies to JUH’s quote, though. I used “infamous” as a funny way to say “not famous, but somewhat known” (and yes, I know Latin and what the words really mean). Hraban

Joaquín Ataz López

3:10 a.m.

...

I used “infamous” as a funny way to say “not famous, but somewhat known” (and yes, I know Latin and what the words really mean). That was my understanding. Infamous=Not famous; that is, not as well known as others. A slight play on words.

-- Joaquín Ataz López Departamento de Derecho civil Universidad de Murcia - España

jbf

3:32 a.m.

Unfortunately, despite all that has been said, we have to realise what words actually mean in English, and 'infamous' has a negative connotation. So I recommend rephrasing this and perhaps the entire paragraph so that it presents a positive perspective on ConTeXt. But if you mean 'less known' then simply say that: ConTeXt is the less known alternative to LaTeX. and rather than 'growing minority', say 'growing number'. We do not say 'ambitioned enthusiasts' in English, but we could say 'ambitious enthusiasts'. Julian On 17/4/24 19:10, Joaquín Ataz López wrote:

...

...
I used “infamous” as a funny way to say “not famous, but somewhat known” (and yes, I know Latin and what the words really mean). That was my understanding. Infamous=Not famous; that is, not as well known as others. A slight play on words.

Bruce Horrocks

5:57 a.m.

...

On 14 Apr 2024, at 12:21, garulfo@azules.eu wrote:

Hi all,

I just discover the Diátaxis documentation framework :

I'd be more confident if you had started by saying "I've been using the Diátaxis for the last ten years and have used it on multiple projects". ;-)

...

- https://www.diataxis.fr/ - 30min video : "What nobody tells you about documentation", https://www.youtube.com/watch?v=t4vKPhjcMZg , from Daniele Procida at PyCon 2017

As I understand it, it can help both readers and writers of the documentation by clarifying the purpose of each element.

So I started a potential new "welcome page" : https://wiki.contextgarden.net/Main_Page2

The main lines would be : - Tutorials: installation pages, step by step examples - How-to guides: most of the existing wiki pages which are not https://wiki.contextgarden.net/Commands/ ... - Discussions and manuals: most of the existing manuals - Reference : the pages dedicated to commands which already include link to mailing list, stack exchange, ConTeXt's source - https://wiki.contextgarden.net/Category:Commands - https://wiki.contextgarden.net/Special:PrefixIndex?prefix=Command%2F

To match the logic of Diátaxis, maybe some material from command pages should be moved from "Reference" to "How-to guides", for example, when the examples go beyond "pure description" and begin to deal with "how-to" cases, e.g. : - Reference for setuphead: https://wiki.contextgarden.net/Command/setuphead - How-to guides for headings: https://wiki.contextgarden.net/Titles

If it make sense, and according to your feedbacks, I can continue to reallocate existing contents.

Thanks for your feedback and thoughts.

I'm going to be devil's advocate and say that the Context documentation is *already* in the Diátaxis framework - just not in one place on the Wiki. - There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants. - There are "My Way" guides linked from the Wiki and the PragmaADE website that fit into the "How-To Guides" quadrant. - And the wiki itself is the "Reference" quadrant. Clearly these can always be better but they are there already. My recommendation would be to use the wiki as the reference quadrant and, apart from the first few "main pages" for people who land there from a web search, it should focus on being the reference manual. Beginners should be directed to the books. Regards, — Bruce Horrocks Hampshire, UK

Henning Hraban Ramm

6:17 a.m.

Am 17.04.24 um 13:57 schrieb Bruce Horrocks:

...

- There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants.

Which published books do you mean? I know of Alan Braslau’s book, AFAIK that will be published in French “soon” and probably later in English. My German book is still not ready, while I work on it regularly. Of course there are a lot of PDFs (most with sources), not only in the distribution, but also in https://github.com/contextgarden/not-so-short-introduction-to-context Hraban

Bruce Horrocks

18 Apr 18 Apr

6:48 a.m.

...

On 17 Apr 2024, at 13:17, Henning Hraban Ramm wrote:

Am 17.04.24 um 13:57 schrieb Bruce Horrocks:

...
- There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants.

Which published books do you mean?

Not published in the sense of having an ISBN assigned but the ones I had in mind were: - "ConTeXt Mark IV An Excursion" by Ton Otten (ma-cd-en.pdf in the distribution) - "A not so short introduction to ConTeXt Mark IV" by Joaquín Ataz-López and your in-progress one. Regards, — Bruce Horrocks Hampshire, UK

Garulfo

17 Apr 17 Apr

3:25 p.m.

Le 17/04/2024 à 13:57, Bruce Horrocks a écrit :

...

...
On 14 Apr 2024, at 12:21, garulfo@azules.eu wrote:

Hi all,

I just discover the Diátaxis documentation framework :

I'd be more confident if you had started by saying "I've been using the Diátaxis for the last ten years and have used it on multiple projects". ;-)

...
- https://www.diataxis.fr/ - 30min video : "What nobody tells you about documentation", https://www.youtube.com/watch?v=t4vKPhjcMZg , from Daniele Procida at PyCon 2017

As I understand it, it can help both readers and writers of the documentation by clarifying the purpose of each element.

So I started a potential new "welcome page" : https://wiki.contextgarden.net/Main_Page2

The main lines would be : - Tutorials: installation pages, step by step examples - How-to guides: most of the existing wiki pages which are not https://wiki.contextgarden.net/Commands/ ... - Discussions and manuals: most of the existing manuals - Reference : the pages dedicated to commands which already include link to mailing list, stack exchange, ConTeXt's source - https://wiki.contextgarden.net/Category:Commands - https://wiki.contextgarden.net/Special:PrefixIndex?prefix=Command%2F

To match the logic of Diátaxis, maybe some material from command pages should be moved from "Reference" to "How-to guides", for example, when the examples go beyond "pure description" and begin to deal with "how-to" cases, e.g. : - Reference for setuphead: https://wiki.contextgarden.net/Command/setuphead - How-to guides for headings: https://wiki.contextgarden.net/Titles

If it make sense, and according to your feedbacks, I can continue to reallocate existing contents.

Thanks for your feedback and thoughts.

I'm going to be devil's advocate and say that the Context documentation is *already* in the Diátaxis framework - just not in one place on the Wiki.

- There are at least two books, and a third being written but not yet released: these fit into the Tutorials and Explanation quadrants.

- There are "My Way" guides linked from the Wiki and the PragmaADE website that fit into the "How-To Guides" quadrant.

- thank you for these reminders

...

- And the wiki itself is the "Reference" quadrant.

...

Clearly these can always be better but they are there already. My recommendation would be to use the wiki as the reference quadrant and, apart from the first few "main pages" for people who land there from a web search, it should focus on being the reference manual. Beginners should be directed to the books.

- Thanks again, the comments are helping to identify a robust method of distributing content across the quadrants. - exactly, it's not a question of proposing new documents, but of proposing another complementary way of accessing and browsing existing ones. - Actually, the wiki is (or can be) a hub for the 4 needs: - "Reference" like https://wiki.contextgarden.net/Command/setuphead - "How-To Guides" like https://wiki.contextgarden.net/Titles - "Tutorials": - hosted https://wiki.contextgarden.net/Detailed_Example - linked https://github.com/mpsmath/stepbystep - "Explanation" : mostly linked manuals and books https://wiki.contextgarden.net/Command/setuphead and https://wiki.contextgarden.net/Titles are examples of how difficult it can be to understand where to find a particular information. It might be worth keeping only the key examples on reference pages like https://wiki.contextgarden.net/Command/*** and moving the "how-to" examples to a separate page (or pages).

...

Regards, — Bruce Horrocks Hampshire, UK

___________________________________________________________________________________ If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl webpage : https://www.pragma-ade.nl / https://context.aanhet.net (mirror) archive : https://github.com/contextgarden/context wiki : https://wiki.contextgarden.net ___________________________________________________________________________________

Henning Hraban Ramm

18 Apr 18 Apr

12:32 a.m.

Am 17.04.24 um 23:25 schrieb Garulfo:

...

- exactly, it's not a question of proposing new documents, but of proposing another complementary way of accessing and browsing existing ones.

- Actually, the wiki is (or can be) a hub for the 4 needs: - "Reference" like https://wiki.contextgarden.net/Command/setuphead - "How-To Guides" like https://wiki.contextgarden.net/Titles - "Tutorials": - hosted https://wiki.contextgarden.net/Detailed_Example - linked https://github.com/mpsmath/stepbystep - "Explanation" : mostly linked manuals and books

https://wiki.contextgarden.net/Command/setuphead and https://wiki.contextgarden.net/Titles are examples of how difficult it can be to understand where to find a particular information.

It might be worth keeping only the key examples on reference pages like https://wiki.contextgarden.net/Command/*** and moving the "how-to" examples to a separate page (or pages).

I agree. Let’s accept this as a rule for further wiki editing. Also, explain parameters with top priority in Command/setup* pages (keeping them in Command/define* pages etc. doesn’t hurt, but at least experienced users should know where to find something without searching). Hraban

garulfo＠azules.eu

17 May 17 May

2:40 p.m.

I have tested on 2 pages : - https://wiki.contextgarden.net/Sciences (only mathematics part) - https://wiki.contextgarden.net/Fonts After these tests, I think this may help users to find their way around the various sources of documentation : In one small table he/she has an overview of the documentation for a given topic, : - the few key tutorials - link to one "main wiki page" about the topic - the few key manuals - the reference for commands I'm not sure I've selected the few documents that are considered by the community as the key tutorials. Thanks for your feedback again. PS : in order to benefit from mediawiki page organization features, I moved some pages, for example wiki.contextgarden.net/blablabla ==> wiki.contextgarden.net/Topic/blablabla

Bruce Horrocks

18 May 18 May

5:27 a.m.

On 17 May 2024, at 21:40, garulfo@azules.eu wrote:

...

I have tested on 2 pages : - https://wiki.contextgarden.net/Sciences (only mathematics part) - https://wiki.contextgarden.net/Fonts

After these tests, I think this may help users to find their way around the various sources of documentation : In one small table he/she has an overview of the documentation for a given topic, : - the few key tutorials - link to one "main wiki page" about the topic - the few key manuals - the reference for commands

The fonts page is a lot better than before[1], IMHO. I would prefer the table were 90% width rather than 50 but that is minor. So is the plan to go through each of the main headings in the left side-bar and make the same type of change?

...

I'm not sure I've selected the few documents that are considered by the community as the key tutorials. Thanks for your feedback again.

I don't think that is a problem - the Wiki can be updated by others as long as the layout/structure of the page is clear so people know where to add links.

...

PS : in order to benefit from mediawiki page organization features, I moved some pages, for example wiki.contextgarden.net/blablabla ==> wiki.contextgarden.net/Topic/blablabla

[1] Previous style for reference: https://web.archive.org/web/20231116125758/https://wiki.contextgarden.net/Fo... — Bruce Horrocks Hampshire, UK

garulfo＠azules.eu

19 May 19 May

6:44 a.m.

...

So is the plan to go through each of the main headings in the left side-bar and make the same type of change? Yes.

Maybe new ones will have to be added

Age (days ago)

Last active (days ago)

List overview

Download

17 comments

9 participants

participants (9)

Bruce Horrocks
Garulfo
garulfo＠azules.eu
Hans Hagen
Henning Hraban Ramm
jbf
Joaquín Ataz López
Peter Hopcroft
Thomas A. Schmitz

Wiki - test/proposal to further clarify documentation

tags

participants (9)