Talk:Main Page
Comments on Main Page
I really like the new look of the wiki! --Alan
Under the 'News', it should be - On January 2, 2021 (& not 2020), availability of "A not so short introduction to ConTeXt" v1.6 by Joaquín Ataz-López --Ramkumar
General ConTeXt Questions
This is not the place to ask general questions about ConTeXt. If you have a longer question, the best thing to do with it is create a new page (see Wiki:Editing for how to do that) with a description of the problem, and put the special text {{howto}} in it, which will cause it to be listed on the page. If you have a short question that is appropriate for the FAQ, you can add it there, and leave the answer blank. If you have a question that you wish to discuss, the best place for that is the ConTeXt mailing list or the "Discussion" page associated with a particularly relevant Wiki page, though you can also use the FAQ's "Talk" page if there's not an obvious choice.
History
January 2025, improving wiki structure + wiki rendering
Before and after images are on a separate page.
Again thanks to Taco and Hans.
- 12 macro topics as main pages, gathering links to subpages (no done 100% but for a vast part of the wiki)
- 1 welcome page for each macro topic = 1 "short" page, same design for each, based on a quadrant to facilitate navigation according to need, and which try to provide an exhaustive overview of what is available:
- tutorial: starter material (from existing wiki page + new ones)
- how-to (suppose you are ok with tutorial): existing wiki pages about more advanced content + links to wiki category pages about the topic
- explanation (mostly docs and presentations, but sometimes also specific pages)
- referential: mostly links to wiki category command pages about the topic
- New wiki features
- improved quality of pdf to png image conversion.
- source=sidebyside available for context tag
- templates for display of manual and library of manuals
- updated css, should be better now on mobile
- Remarks on changes in navigation structure
- Bibliography tuto, Bibliography and PDF navigation are now in References notes and floats
- Text editors, Languages and XML are in Input and compilation
- "Sciences" is split in Mathematics and Chemistry
- Units is in Math with links from Dimensions (others links should be added)
- ConTeXt_Development is now part of ConTeXt and Lua programming
- "ConTeXt Tools" content split between to Input and compilation and ConTeXt and Lua programming
- Finally Graphics and media includes Graphical programming : Create charts, graphs, and custom visuals, Frames overlays boxes collectors : Leverage ConTeXt fundamentals to build advanced and customized typesetting structures.
Desired objective (combined with the improvement of rendering quality and css trick to highlight the renderings)
- help users make more sense of the different content available
- help users to know where and how to store new material
- to help identify old content (and move it to archives pages)
- to help avoid and eliminate duplicates
2020
- On July 25, 2020, the NoTitle wiki extension was installed.
- Since July 1, 2020, this wiki and live.cg.net and source.cg.net are all using ConTeXt
version: 2020.06.30 17:30 (LMTX). - Since May 28, 2020, we are running on a new mediawiki core, version 1.34.1.
- The 13th ConTeXt Meeting took place in Bassenge-Boirs, Belgium on September 16–21, 2019.
just a typo (which I cannot fix myself)
'russian' instead of 'Russian' --Pablo Rodríguez (talk) 17:50, 29 June 2022 (CEST)
quadrants
The quadrants are based on Diátaxis documentation framework, from Daniele Procid, from the Python community. Also used by docs.divio.com, or docs.djangoproject.com for example.
The core idea of Diátaxis is that there are fundamentally four identifiable kinds of documentation, that respond to four different needs. The four kinds are: tutorials, how-to guides, reference and explanation. Each has a different purpose, and needs to be written in a different way.
| Tutorials | How-to guides | Reference | Explanation | |
|---|---|---|---|---|
| oriented to | learning | a goal | information | understanding |
| must | allow the newcomer to get started | show how to solve a specific problem | describe the machinery | explain |
| its form | a lesson | a series of steps | dry description | discursive explanation |
| analogy | teaching a small child how to cook | a recipe in a cookery book | a reference encyclopedia article | an article on culinary social history |
Tutorials
A tutorial is a lesson, that takes a student by the hand through a learning experience. A tutorial is always practical: the user does something, under the guidance of an instructor. A tutorial is designed around an encounter that the learner can make sense of, in which the instructor is responsible for the learner’s safety and success.
A driving lesson is a good example of a tutorial. The purpose of the lesson is to develop skills and confidence in the student, not to get from A to B. A software example could be: Let’s create a simple game in Python.
The user will learn through what they do - not because someone has tried to teach them.
In documentation, the special difficulty is that the instructor is condemned to be absent, and is not there to monitor the learner and correct their mistakes. The instructor must somehow find a way to be present through written instruction alone.
How-to guides
A how-to guide addresses a real-world goal or problem, by providing practical directions to help the user who is in that situation.
A how-to guide always addresses an already-competent user, who is expected to be able to use the guide to help them get their work done. In contrast to a tutorial, a how-to guide is concerned with work rather than study.
A how-to guide might be: How to store cellulose nitrate film (in motion picture photography) or How to configure frame profiling (in software). Or even: Troubleshooting deployment problems.
Explanation
Explanatory guides provide context and background. They serve the need to understand and put things in a bigger picture. Explanation joins things together, and helps answer the question why?
Explanation often needs to circle around its subject, and approach it from different directions. It can contain opinions and take perspectives.
Like reference, explanation belongs to the realm of propositional knowledge rather than action. However its purpose is to serve the user’s study - as tutorials do - and not their work.
Often, writers of tutorials who are anxious that their students should know things overload their tutorials with distracting and unhelpful explanation. It would be much more useful to give the learner the most minimal explanation (“Here, we use HTTPS because it’s safer”) and then link to an in-depth article (Secure communication using HTTPS encryption) for when the user is ready for it.
Reference
Reference guides contain the technical description - facts - that a user needs in order to do things correctly: accurate, complete, reliable information, free of distraction and interpretation. They contain propositional or theoretical knowledge, not guides to action.
Like a how-to guide, reference documentation serves the user who is at work, and it’s up to the user to be sufficiently competent to interpret and use it correctly.
Reference material is neutral. It is not concerned with what the user is doing. A marine chart could be used by a ship’s navigator to plot a course, but equally well by a prosecuting magistrate in a legal case.
Where possible, the architecture of reference documentation should reflect the structure or architecture of the thing it’s describing - just like a map does. If a method is part of a class that belongs to a certain module, then we should expect to see the same relationship in the documentation too.