Documentation automation

Publish Date: Apr 29 '19

14 12

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?

Use a markup language for the documentation
Put it on version control software
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,

Comments 12 total

Dian FayApr 29, 2019
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.
- Daniel CoturelApr 30, 2019
  
  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.
Horst GutmannApr 30, 2019

Also great resources for documentation are the whole Docs As Code / Docs Like Code movement and the WriteTheDocs community 🙂
- Daniel CoturelApr 30, 2019
  
  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.
  - Horst GutmannApr 30, 2019
    
    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 🙂
    - Daniel CoturelApr 30, 2019
      
      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,
      - Horst GutmannApr 30, 2019
        
        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.
Burdette LamarApr 30, 2019

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.
- Daniel CoturelApr 30, 2019
  
  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!
Daniel CoturelApr 30, 2019
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
Jeremy Likness ⚡️May 2, 2019

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.
- Daniel CoturelMay 2, 2019
  
  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,

Add comment

Daniel Coturel @elcotu

Documentation automation

Comments 12 total