DEV Community

Daniel Coturel
Daniel Coturel

Posted on • Updated on

Documentation automation

Hi people,

Due to a past post where several users recommended books about programming or more general bibliography (this is the post: https://dev.to/lightalloy/learning-to-love-software-development-books-5e4) I've read past week the book The Pragmatic Programmer.

I have to say, the book is plenty of interesting stuff and thing I will try to implement during this year. The most inmediate and time-gaining measure, I think, is when the book suggests to automate project documentation.

How?

  1. Use a markup language for the documentation
  2. Put it on version control software
  3. Based on the markup language, generate scripts to the required outputs: HTML, PDF, EPUB or whatever you need

I think this is a great concept, and I will work on this in my organization for the next months. And I would like to read from you if you had any experiences with this and recommend tools, etc.

Saludos,

Top comments (12)

Collapse
 
dmfay profile image
Dian Fay

I wrote something about this a while back; some of it's GitHub specific but not all. I have since moved the project on to an independent .org as a static site which checks out the project and runs the automated toolkit against it, deployed to hosting with a quick scp; I like it this way, but that's for a single open source project.

Collapse
 
elcotu profile image
Daniel Coturel

Thanks for your feedback. I read your post, went through the documentation of MassiveJS and I think your experience will be useful for what I want to achieve.

Collapse
 
elcotu profile image
Daniel Coturel

Thanks everyone for your answers. By now, I think what I have to do is:

  1. Choose a markup language that covers my needs as a base. For instance, markdown, or some XML.
  2. Pick a tool or a set of tools to do the conversion to other needed formats. I've come to this tool that seems to cover a lot of needs: pandoc.org
  3. Survey all of my required output formats and start planning for a development phase to create the scripts that automate the generation of those outputs
Collapse
 
burdettelamar profile image
Burdette Lamar

A different flavor of automation for documentation: Keep Your Example Code Green.

Every time you run the tests, you should also run the example code and re-assemble the docs.

Collapse
 
elcotu profile image
Daniel Coturel

Hi Burdette, I'll examine your post. Did a fast reading by now. It covers a good portion of what I have in mind. Thanks for bringing it here!

Collapse
 
jeremylikness profile image
Jeremy Likness ⚡️

Nearly all of Microsoft's documentation is fully automated this way.

As I understand it, the documentation is one of the largest repositories hosted on GitHub (it lived there even before the aquisition).

The public can contribute with pull requests and track issues. The documents are all markdown format and a full-automated build process compiles these into the SEO-friendly website. We use the built-in GitHub features to review and comment on submissions and have tags that automate parts of the process like excluding work in progress until it's approved for release. There is also a process to generate other formats like PDF, which is what I did for a free eBook about serverless I hosted on the platform.

You can read the details here if you're interested.

Collapse
 
elcotu profile image
Daniel Coturel

Hi Jeremy,
This is very useful and oriented to what I was looking for. Thank you for bringing it in.
Do you have details about the process to generate other formats?
Saludos,

Collapse
 
zerok profile image
Horst Gutmann

Also great resources for documentation are the whole Docs As Code / Docs Like Code movement and the WriteTheDocs community 🙂

Collapse
 
elcotu profile image
Daniel Coturel

Hi Horst,
I've been reading this page due to your suggestion:
writethedocs.org
I think this is the approach proposed by the author of The Pragmatic Programmer. Have you experienced some of this on your own practice?

By the way, seems clear that I have to learn intensively markdown language.

Collapse
 
zerok profile image
Horst Gutmann

In my experience, documentation is as important to the final product as code. Keeping both in sync is much easier when both a stored in the same repository and can therefore also be reviewed with the same tools (pull requests as code review).

Personally, I like working with Markdown for short documents (e.g. READMEs) and Sphinx/RestructuredText or Asciidoc for large documentation bodies like handbooks, guides, references, and so on.

For all of them there’s also strong tooling support available which helps you, for instance, to do automated spell- or link-checking.

I hope this helps and gives you some ideas for your projects 🙂

Thread Thread
 
elcotu profile image
Daniel Coturel

This indeed helps me a lot. If you don't mind the question, why do you prefer Markdown for short documents? Is there a lack of functionality that makes it unsuitable for large documents?

Saludos,

Thread Thread
 
zerok profile image
Horst Gutmann • Edited

That’s pretty much it. Markdown itself only supports basic markup like bold, italic and linking, but if you, for instance, want to mark things like keyboard shortcuts, menu entries etc. (which is quite common in manuals and userguides), Asciidoc and Sphinx offer far more.

The technical term for the feature I’m referring to is “semantic markup”. For manuals etc. this is essential.

Markdown, on the other hand, has ether advantage that it is far more common, so onboarding new people is easier.