13

Here is a big post about new documentation project: Warlords of Documentation: A Proposed Expansion of Stack Overflow

I think, that LaTeX doesn't have good online documentation, almost everything is in pdf and is not structured very well. To search something about tikz I have to open the big pdf file.

It would be good to move at least some docs to stack, but I think, that nobody would like to do it. Maybe, the authors of packages?

| |
  • 10
    The usual problem comes up: LaTeX is actually about typesetting so to have code and demos in one place works best in PDF format. That's very different from documenting say C. – Joseph Wright♦ Sep 4 '15 at 10:56
  • 1
    @JosephWright Online documentation has benefits over PDF: it's faster to open in browser and to search. I learned more about latex from this site than from PDFs. – user4035 Sep 4 '15 at 10:59
  • @JosephWright Anyway, that what I though: nobody is interested to spend time on that. – user4035 Sep 4 '15 at 11:00
  • 5
    You give up rather quickly. That one person, even if it is @JosephWright says that there are problems, doesn't mean that there isn't anybody who likes the idea and would be willing to work on it. (You may of course be correct in your thought though ...) – Torbjørn T. Sep 4 '15 at 11:15
  • @user4035 I don't necessarily mean that this applies in all cases: there are a range of programming tools for LaTeX where the typesetting issue doesn't apply. – Joseph Wright♦ Sep 4 '15 at 11:31
  • 2
    You should also check PDFs, they teach you things that no online document might mention because they are written by the authors themselves. – percusse Sep 4 '15 at 11:31
  • 1
    I agree that LaTeX online documentation is far from being perfect. There is no reference system which can be used across distributions. ConTeXt has this nice XML file which you can use to generate documentation. See for example the ConTeXt wiki or others (serach for texshow / etexshow / texshow-web). – topskip Sep 4 '15 at 11:34
  • 2
    It would be interesting to see how you open the equivalent of the tikz manual in a browser and search it ... Small documentations are fine in a browser. But for large things like tikz, source3, biblatex I would always prefer a pdf. I don't like large wikis where you have to jump around and never know where you are, if the page is up-to-date and how it connects to other parts. Also I want the documentation to be accessible offline. – Ulrike Fischer Sep 4 '15 at 12:02
  • @UlrikeFischer tikz manual must be split into chapters with an index. C++ documentation is huge but it's splits across many documents and is not stored in 1 big file, – user4035 Sep 4 '15 at 12:03
  • 1
    No. See the answer Warlords of Documentation: A Proposed Expansion of Stack Overflow - documentation is hard and needs professional help. – Martin Schröder Sep 6 '15 at 12:13
  • While the project is interesting and I'm planning to participate, I'd want to see failover plans for the documentation before I call it an 'official' source of anything. – Sean Allred Sep 7 '15 at 18:05
  • I think LaTeX has excellent documentation. I'm thoroughly impressed by the detail of documentation for packages like TikZ and I don't understand how anyone can have the time to so meticulously document everything. – gerrit Sep 9 '15 at 15:59
  • 1
    I find the idea behind the documentation project rather chilling. Wanting to take over all of anything strikes me as problematic. These are private sites: they are subject to the wallets, whims and fortunes of a particular small group with a particular agenda and particular interests. I would hate to see information about free software hostage to that - however benign the intentions and whatever the drawbacks of existing systems. I'm especially disturbed by the wish to become a repository for official documentation. And there is some arrogance here, also... but that's not so disturbing. – cfr Sep 15 '15 at 12:11
21

Couple thoughts I have on this topic:

  1. People mix user manual and documentation. These are two very different things. Every LaTeX package that makes it to CTAN has to be documented, at least to some extent. Most packages are documented well, using docstrip or similar tools; however, this is often the technical documentation, which may not be what first-time users looks for. For first-time users there are other resources, though: this site, for instance.

  2. Stepping into a project that does not seem well thought out sounds like anything but a good idea. If something has to happen, it need not happen now and here.

  3. Do we want people at StackOverflow --- who have often very stupid (read, blatantly wrong) LaTeX habits themselves --- to produce documentation and use examples for anything LaTeXy? The internet is flooded by these, and people look at them rather than open the documentation.

  4. People can get very good advice on a lot of things here. If they need to know how something is done, most likely it's covered by an easy-to-find question on this site. If it's not covered, then either it's too primitive, too technical to be covered by a community-driven documentation, or simply can be asked here.

Conclusion I made for myself: Should we intend to participate? No, at least for now.

| |
  • 3
    Re »Every LaTeX package that makes it to CTAN has to be documented« – I've never seen that requirement anywhere. Do you have a source? AFAIK only a README is required. Documentation is certainly recommended, though. Quote from ctan.org/upload: »Al­most all pack­ages should have doc­u­men­ta­tion be­yond the [...] README.« (BTW: is that a user manual or documentation of code? I don't know…) All my packages have a user manual but none has a real code documentation. – cgnieder Sep 4 '15 at 12:41
  • 2
    @clemens -- i'm not sure about the documentation requirement for ctan, but i am pretty sure about this: if a package on ctan is to be accepted into tex live (and in general, nothing is accepted into tex live unless it is first posted to ctan), it has to have documentation, including the source to reproduce it. some very good material has been refused acceptance on tex live because the documentation source was lacking. (documentation does not necessarily imply code documentation, but something for the user.) – barbara beeton Sep 4 '15 at 13:33
  • 1
    @barbarabeeton I'm not sure that's entirely true. AFAIK also for TL a package doesn't have to have documentation bit if it does the source has to be given as well or the documentation (not the package itself) won't be included in TL, see point 3 in tug.org/texlive/pkgcontrib.html – cgnieder Sep 4 '15 at 13:42
  • @barbarabeeton I may be wrong, though :) – cgnieder Sep 4 '15 at 13:44
  • @clemens -- you're essentially correct (no generated documentation included without source). but ctan does require at least a "readme" file and a statement of what the purpose of a contribution is, so at least that much "documentation" is going to be present. (as for something more thorough, there's always peer pressure.) – barbara beeton Sep 4 '15 at 13:49
  • 2
    @yo' -- perhaps i misinterpreted something in the "warlords of documentation" posting (haven't gotten all the way through it yet). i think it was implied that a subject-area stack* group could set up its own documentation node. copying really good, authoritative answers to such a node as recommendations might make it easier to find them, or related "smaller" answers could be edited into topics, taking care to stress "best practices". question is, who's got the time either to do or to monitor, or the "authority" to be accepted to do it? – barbara beeton Sep 4 '15 at 13:58
10

I wonder if StackOverflow would follow requirements of GNU FDL, LPPL, or other licenses of the original documentation, for parts SO would take over.

Note, in official documentation in PDFs and on CTAN etc., where we would take over parts from documentation written on SO, we would always have to follow the SO licensing, which is cc by-sa 3.0 with attribution: backlinks to each post and each involved user.

| |
  • Yeah, this also makes participation impossible. But everybody agreed, that online documentation for LaTeX can be improved significantly. – user4035 Sep 6 '15 at 9:00
  • 1
    @user4035 Yes, online access and perhaps collaborative documenting. I made a start with TeXdoc.net which I hope we can improve. Btw. I experimented with tex4ht to get wonderful huge manuals such as for TikZ exported in digestible HTML versions. – Stefan Kottwitz♦ Sep 6 '15 at 11:49
  • "I experimented with tex4ht to get wonderful huge manuals such as for TikZ" - this was my dream. Where can I see it? – user4035 Sep 6 '15 at 15:00
  • The proposal is quite clear: (a) SO documentation will have the same CC license as other SO materials, and (b) they envisage new work, not to "take over" the existing manuals. – alexis Sep 10 '15 at 23:19
  • @alexis (b) I spoke of parts. I assume SO (users) will copy some parts in case they don't start from scratch and write everything differently. (a) it's to clarify if SO can publish under the same CC license when original parts come via GNU FDL or LPPL. Not using any part of original documentation would solve license questions. – Stefan Kottwitz♦ Sep 11 '15 at 9:57
  • 1
    I can't see this could ever be two way. At most, SE could take documentation from official sources, if the particular licence allowed it etc. Official documentation couldn't take documentation back from SE without getting a suitable licensing agreement from each user who contributed, which would always make it impractical. In any case, why add YASAD to the mix? (Yet Another Source of Alleged Documentation) The next new thing is always supposed to be the silver bullet and it never is because the real answer is to read the official documentation. Maybe I'm too old-fashioned. – cfr Aug 4 '16 at 3:11
5

The LaTeX Reference Manual is quite explicit about Contributions wanted. It is online, meaning HTML, among other formats.

| |
  • 1
    There is also the wikibook that is often read by newcommers and that needs attention very very bad. Quite a few bad/wrong advice there. But: no shiny (but worthless) badges and no reputation there. – Johannes_B Sep 8 '15 at 15:14
  • I don't know how much revisions of the WB are welcome but I see that the latest revision is Jan 2015. OTOH, FWIW, refman was revised this morning. – Jim Hefferon Sep 8 '15 at 18:45
  • What i meant was more of a contribution lacking because of missing rewards. I get the mails for latex-refman (not contributed yet) and made some revisions to the wikibook. But the amount of work to get the WB up to date is huge, more annoyingly: I don't agree with some of the content there. Question is: How to get people to contribute? – Johannes_B Sep 8 '15 at 19:01
4

The TeX community has an english FAQ, a german FAQ, a wikibook (translated into multiple languages) and several other places where Information (of any quality) is stored.

Advantage here on the SE-network: shiny badges, reputation for participating, which is a motivator.

Ok, nice, cuople of general things though.

  • Who is doing the review?

High reputation does not mean high knowledge of a specific topic. What about robo reviews?

  • Often documentation is lacking in examples, or the examples are trivial and don't demonstrate typical use.

This is from the initial question. Agreed, either examples are non-existent or hard for a starter to process/understand. But doesn't that mean we need examples instead of documentation?

Active members of the community could make up examples of the often requested stuff, mail it to package authors and ask them to include the examples in the doc. Sanity check included. Sanity check missing here on the network (i.e. acceptible review).

  • Who choses how to document a topic?

For example, let's assume the topic of page headers and footers? We have fancyhdr, we have titleps and we have scrlayer-scrpage in general use. All packages work with the standard classes. The first two are not recommended with KOMA-script. memoir has stuff implemented, no package needed. How to document that on a website (here, wiki, faq, whereever) without confusing a beginner? And we are talking about beginners here.

I have seen so many bad advice (probably given quite a bit myself) in forum posts, blog-posts, wikibook and others, that i am scared, that instead of helping it creates another source of confusion.

Remember: You cannot just delete stuff from the internet once it is written. There will be proof somewhere, that i am a penguin.

| |
  • I'm sympathetic to parts of this but I think examples vs. documentation is a false dichotomy. – cfr Sep 12 '15 at 2:48
  • maybe the wording was wrong, i think we need more examples along with the documentation. – Johannes_B Sep 12 '15 at 15:03
  • 1
    In that case, I agree with the penguin ;). – cfr Sep 12 '15 at 16:28

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .