How to Generate Wonderful Documentation?

1

Do you know how to generate documentation for an application that people would read? I wish to produce something for my company on the order of:

  1. Heroku Documentation: https://devcenter.heroku.com/

  2. SaltStack Documentation: https://docs.saltstack.com/en/latest/

How do you keep the documentation in sync with the source code?

How do you generate automatically documentation from the source code comments and docstrings in multiple formats?

What are the tools to use?

The code we wrote is in Python and Django.

Many thanks for your advice in advance!

Yours,
John

2

I sure wish I knew for sure. Some companies hire technical writers to do it, and I’m sure that the best documentation will cost good money.

3

I actually find enjoyment writing documentation. As others have said you can pay technical writers as well.

There are also many documentation generators, I’ve only had experience with doxygen but you’ve piqued my interest. Here is a list of some https://en.m.wikipedia.org/wiki/Comparison_of_documentation_generators

4

Isn’t there inline function auto-documentation that you can write? Similar to C#.

Not sure if that is what you’re referring to.

5

Never mind, completely missed the links :expressionless:

6

Thanks for the replies @zaclem01. @PortableStick and @coloradomountain.

I found out that SaltStack sometimes answers you questions:

They gave me a great answer.