Talk:Main Page
Contents
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.
The Main Page and its target audience.
It seems to me that, currently, the Main Page is geared towards "initiated users", and isn't as helpful as it could be for newcomers.
ConTeXt is such a good project! But its existence almost feels like a well gate-kept secret in the TeX community. I, myself, only found it by accident, after having spent years wishing such an improvement over LaTeX existed.
Right now, if someone wanted to migrate to ConTeXt (or even learn ConTeXt from the start), coming to this wiki's Main Page would be the most obvious first step. But from then on, the path is not so clear. Questions such as "What is ConTeXt", "Where can I get it" and "How can I use it", "How is it different from LaTeX" are not clearly answered here, and there's no clear route to get up and running with ConTeXt, in general.
I think the most important things that the Main Page currently lacks are the following links:
- Install ConTeXt
- A no-brainer, something prominently displayed on the main page of every software project. I see there's an "Installation" link on the side panel, but that's too hard to find. In my opinion, this should be immediately and clearly visible whenever the Main Page loads for the first-time visitor.
- ConTeXt Quick Start
- A page that walks a user from installing ConTeXt, to what ConTeXt is, basic commands, and getting their first PDF document. It's important that it come "with batteries included": the whole thing should be contained in one page. I'd personally create two versions of it: one for absolute beginners and one for those coming from LaTeX, and have links to both of them in the Main Page (or at least have a "If you're already LaTeX user, visit the Quick Start for LaTeX users" banner at the top of the beginners' Quick Start page).
Apart from that, I think this wiki could also offer a somewhat longer-form tutorial. There are tutorial pages in each of the "12 Sections" listed in the Main Page, and they're great, but they're too scattered around IMO. It'd be good to have a starting "Tutorial page", that not only links the existing tutorials together, but does so in a didactic manner, forming a cohesive whole, with clear steps. Right now, if a user wanted to learn from each Section's tutorial page---in the order they're presented---, they'd only learn about basic formatting commands in the fifth tutorial!
I've started to wonder what such a "Quick Start" page could look like in my profile page, but there's nothing much there yet. I think Mikael Sundqvist's Book tutorial is the best ConTeXt tutorial I've found; perhaps we can make it a bit shorter.
What do you think?