Re: [NTG-context] State of documentation of ConTeXt?

As I wrote in another thread, the state of the docs worries me too. I take it that the suggestion to study the source was not serious, and perhaps it is indeed a matter of priorities. As a new user I have a strong opinion that the documentation should be a higher priority than it seems to be. All the arguments about how many person-hours it would take and the huge task it is, in my eyes, only furthers the point that it is not considered as important as doing "real development". I consider the docs a core part of the project, and the code another part, hence the disagreement in regards to the priorities. Pro-bono or not is not an issue, since time is spent on the project in some form. Writing features that few people know about and are able to use is only half of the dev work. But I get it that documenting is a pain, and seemingly frivolous work. The separate manuals may have been good, but they look fragmented and there is no unified docs to go to when in doubt. And having one place to go is even easier to maintain than many. The wiki is a nice idea, but it needs much more rigour to function as real docs. Some suggestions. I'm assuming some form of wiki-like website that can be the contextgarden or (preferably) another official docs/wiki/wiki-like site. All the content of the manuals should be unified in this site. If a crowdsourcing/users-can-do-it approach is taken, a clear structure needs to be previously laid out, so that we know what blanks to fill. And even with collaboration/feedback, core people should do it. It is important that reviewing and check marking the new edits be done by some authoritative group, so that the community knows what to trust, what should work as documented so that we can report real issues. It is important to label the information as reviwed and up to date, and to which version it applies, mkii/mkiv If this structure is put on top of the context garden, some labeling is needed to distinguish the extra pages from the structural docs pages. There are many good examples out there of good docs structure and presentation. I'm willing to collaborate what I can with my limited knowledge and time, even if little while writing my master's thesis. Sorry to annoy with this again, YT 2014-07-15 11:55 GMT-03:00 luigi scarso :

On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda wrote:

...

On 14 Jul 2014, at 19:29, Hans Hagen wrote:

quite some sub-systems are described in their own manuals (fonts, tables, xml, ...) and these manuals are quite up to date (and easier to maintain than one big fat manual

also, additional documentation is something that users need to participate in (just pick a topic)

even if it has high priority, that doesn't mean that those involved have much free time left to do that next to their regular work (as usual most development is done in spare time)

so, patience is needed,

I like ConTeXt (still do, I liked its approach when I first encountered it). But the project is more the ongoing private tinkering of a small in-crowd (that communicates with some followers).

ConTeXt is managed a bit like a small group of researchers sharing a couple of complex and undocumented models/programs and tinkering with them as they go along. It’s an activity without formal design, but with a lot of trial-and-error/testing.

Given that status (and the fact that it has had that status for over a *decennium*), I don’t expect it to ever become a serious product that is (semi-)professionally managed. I prefer content over management every day, but something like this needs some minimal management. That requires both time (=money) and capabilities. Besides, the tinkering researchers may not be inclined to do that, they want to tinker.

BTW, you can’t be serious asking the *users* to provide the documentation, can you?

These are still good

Fonts in ConTeXt Layouts in ConTeXt MetaFun manual MKII - MKIV, the history of LuaTeX

http://www.h2o-books.com/catalog/5

-- luigi

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

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context webpage : http://www.pragma-ade.nl / http://tex.aanhet.net archive : http://foundry.supelec.fr/projects/contextrev/ wiki : http://contextgarden.net

___________________________________________________________________________________