8

I know there is already the question about adding documentation here. However, the Stack Overflow documentation has a section for LaTeX documentation where several people are trying to pull something together. I think that as a community, we should help in this endeavor. I personally have tried to help as best I can, writing about the (admittedly few to none) topics I feel like I can say something about and trying to review edits and such. I know, though that there are many people on this site so much more suited to this endeavor than I am. The consensus on the previous question was that we should wait and see if the documentation was a success. But shouldn't we help make it a success? Some of the people on this site wrote the packages the people on Stack Overflow are trying to document. Others are just amazingly good with LaTeX. Why don't we try to help those on Stack Overflow working on the LaTeX documentation? I know I find it hard to read through the already existent documentation when I'm really just looking for a simple solution, and I think that LaTeX documentation would be of so much assistance to many, that I think working on it fits right in with the goal of this site.

So I guess my question is, why not help?

Note: I should point out that there are some people from TeX.SX working on the documentation.

15
  • Will there be TeX.SX Documentation?
    – Johannes_B
    Commented Aug 18, 2016 at 6:46
  • 2
    Personally, i find the format of the SO-documentatin format extremely rigid and non-suiting for LaTeX documentation.
    – Johannes_B
    Commented Aug 18, 2016 at 6:55
  • 1
    The syntax for LaTeX is always the same, backslash, {} and []. Ok, say the way a tabular is written down is syntax. What is the example then?
    – Johannes_B
    Commented Aug 18, 2016 at 6:55
  • 3
    Furthermore, it already is documented. Some better than other, but it is findable with not very much effort.
    – Johannes_B
    Commented Aug 18, 2016 at 6:56
  • 6
    The 'wait and see' part here to me is 'is this going to work in terms of added value'. There's already lots of LaTeX documentation (I have a shelf of books on it!), the question is will this new material be better than the existing. For LaTeX, we have in addition to good textbooks a lot of good free documentation plus all of the package support stuff (texdoc).
    – Joseph Wright Mod
    Commented Aug 18, 2016 at 7:52
  • 5
    I still don't think SO is a good place for this endeavor
    – percusse
    Commented Aug 18, 2016 at 8:20
  • 12
    I won't work on this "documentation". Imho it can't be a success, as it is "neither fish nor meat" as we would say in german. The texts will be too short and too few to count as real documentation and they will be too long and too many (with to many arcane topics) to be the simple introduction newbies are looking for. Imho the time of the people which "are just amazingly good with LaTeX" are better spent in either answering questions about concrete problems or on improving the latex code.
    – Ulrike Fischer
    Commented Aug 18, 2016 at 8:32
  • 8
    I won't contribute to documentation no part of which can be incorporated into standard TeX distributions. I don't agree with @UlrikeFischer that the time would be better spend improving the LaTeX code necessarily. I think that time may also be well spent on improving documentation. But I think efforts should be focused on improving official documentation which can be included in all TeX distributions. (I also find the overall aims of the documentation project disturbing, not to say chilling, and frankly hope that it does not succeed in fulfilling them. Free software needs free documentation.)
    – cfr
    Commented Aug 18, 2016 at 22:38
  • 3
    @cfr you are right regarding the "official" documentation. For me this was included in "latex code": someone who writes a package should also document it. (Good) books are naturally fine too.
    – Ulrike Fischer
    Commented Aug 19, 2016 at 6:34
  • 2
    I believe that at the same time as TeX.SE went live, all TeX-related questions should have been made off-topic for SO. There is really no point in duplicating documentation. Besides, most of the TeXperts are here, not there.
    – Matsmath
    Commented Aug 19, 2016 at 17:29
  • @UlrikeFischer Oh, I misunderstood. I thought you had meant code as opposed to documentation, but if you're including documentation, I agree with your conclusions. (I haven't looked at the project really, so I'm not in a position to agree or otherwise with the particular points you make, but I'm sure you're right.)
    – cfr
    Commented Aug 19, 2016 at 21:11
  • 8
    Having looked at it, I also agree with those who've pointed out how ill-suited the rigid format is to documenting LaTeX. The 'syntax' section for the topic on bibliographies is an outstanding example of just how confusing things can be when you try to fit hexagonal pegs into round holes. The format is, I assume, intended to document one command per topic. 'Bibliographies' is not a command of this kind! The topic on environments shows the same problem. The syntax is presented as generic but isn't as it takes no account of environments with optional/mandatory arguments. A topic per macro? Ugh.
    – cfr
    Commented Aug 19, 2016 at 21:32
  • I just had another look at the documentation page and it is .... Better invest time in Working on the Wikibook. Heather, you have contributed quite a bit and you could really do some good work on the wikibook, it is currently in a bad state.
    – Johannes_B
    Commented Aug 24, 2016 at 6:44
  • @Johannes_B, okay, where are the problems? I'd be glad to help any way I could.
    – auden
    Commented Aug 24, 2016 at 11:58
  • 1
    How can we, as a community, improve the LaTeX WikiBook? Our chat room is als filled with discussions. Somewhere on a discussion page in the wikibook are comments by me and Clemens, but it could be the german version.
    – Johannes_B
    Commented Aug 24, 2016 at 16:44

1 Answer 1

Reset to default
2

CTAN does a perfect job IMHO. All package documentation is already there. And then there is Latex section on Wikibooks, which is awesome.

11
  • 5
    sadly, the latex wikibook contains quite a lot of erroneous or misleading information. it is very badly in need of an overhaul!
    – barbara beeton
    Commented Aug 24, 2016 at 21:45
  • 1
    @barbarabeeton I just read the first paragraph for one topic and ... er, left several paragraphs on the topic's discussion page. If this is a 'featured' wikibook, what are the rest like? I know this is mean, but there are excellent books on LaTeX, so it isn't as though this is filling a gap in the market.
    – cfr
    Commented Aug 25, 2016 at 2:32
  • 1
    @cfr -- no, the latex wikibook is not "filling a gap" in the obvious way, but it's so easy to find via google that it's apparently gotten very popular. one of my jobs is maintaining most of the tex documentation on the ams website, including recommendations for books and other documentation. i won't include the latex wikibook since the principal part of my job is answering questions for authors who are having problems. i really don't want to have to research where they got bad information, as well as giving them instruction; the latter is more productive.
    – barbara beeton
    Commented Aug 25, 2016 at 12:12
  • @barbarabeeton Indeed ;). I suspect, too, that the wiki-structure makes it appealingly manageable to new users because they don't have to deal with the thought of an entire book. (An entire book obviously being a horror of horrors.)
    – cfr
    Commented Aug 25, 2016 at 12:38
  • And the Stackoverflow documentation structure is kind of wiki-done-wrong, but equally appealing, unfortunately.
    – Alan Munn
    Commented Aug 25, 2016 at 23:23
  • @cfr Are you the person with the font stuff?
    – Johannes_B
    Commented Aug 26, 2016 at 4:48
  • @Johannes_B Probably. Depends which font stuff, but I expect so.
    – cfr
    Commented Aug 26, 2016 at 16:25
  • @cfr I was referring to that en.wikibooks.org/wiki/Talk:LaTeX/Fonts#Very_misleading If it was not your comment, can you add a lnk please?
    – Johannes_B
    Commented Aug 27, 2016 at 8:11
  • @Johannes_B See also mactex-wiki.tug.org/wiki/index.php/Fonts. This needs updating to take account of LuaLaTeX, but I would recommend the material on fonts in the MacTeX wiki, most of which is not specific to Mac OS X. (But I am, admittedly, biased.)
    – cfr
    Commented Aug 27, 2016 at 15:24
  • @cfr Oh, another wiki. :-/
    – Johannes_B
    Commented Aug 27, 2016 at 15:54
  • @Johannes_B Yes. But it should hopefully include less confusion. It certainly did include less confusion., although it was being very heavily vandalised at one point.
    – cfr
    Commented Aug 27, 2016 at 19:24

You must log in to answer this question.

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