Ever since the launch of the Tectonic project, it’s been a bit of an irony that this project to enable documentation has had pretty poor documentation itself. There are a lot of excuses but fundamentally I just never sat down and set up the infrastructure to start writing real documentation.
Thanks to the initiative of @efx that has now changed! Eli set up a stub manual based on mdbook, a system that’s popular in the Rust community, and today I figured out a way to start publishing the results publicly:
I wrote up a quick introduction but otherwise we’re shy of content. I think that there’s broad agreement that the top priority is to better document the CLI interface, but contributions of any kind are more than welcome! I’m not quite sure how best to organize the book, but IMO the best approach is to get stuff in there first and move it around later as we figure out how it should look.
Now the new irony is that our documentation is in Markdown, not TeX, but for the time being my dreams of beautiful HTML output from TeX are just dreams, so we’re being pragmatic.
If you’re interested in this kind of thing, you might be interested to see how we deploy the built HTML — it’s the best system I could come up with for getting this kind of content served via GitHub pages, when there’s a reasonable expectation that we’ll want to graft several different trees of generated HTML onto one URL structure.
Once the book is fleshed out a bit more, we should update the main website to point to it. Another question to consider is which content should go on the website, and which content should go in the book — it’s not obvious to me how to decide that, although a key distinction is that the book is in-repo with the main code, and the website repo is separate. Any thoughts on that?
@pkgw Cool, for what its worth I do have some code tex_gen.rs in my project which does convert markdown to latex, and then runs the result through tectonic.
It is fairly ad-hoc at the moment; pulling markdown out of bytecode, rather than reading it from text files, also generating TeX from strings in the bytecode as well as the Markdown.
However if there is anything that would help there, that I could pull out or refactor I would gladly contribute any useful bits to either mdbook or the tectonic project itself.
Edit: I see there is (new since the last i looked), mdbook-latex plugin, using tectonic already.
I’ll look if anything in the above is useful for that project.
Three cheers to your achieving autopublishing! I think it will help teach new users about the project.
Version 2 will be texbook.
Great question. Initially I think tutorials, and technical documentation seem best alongside the main source code. Putting the documentation next to the actual code makes it easier to synchronize changes whenever internal implementation details or the CLI interface change.
I stumbled across https://www.writethedocs.org/ and it has some helpful guides for writing effective documentation. Somewhere in their guide they mentioned 2 main audiences: developers + users. We could consider that breakdown for the website versus the mdbook.