0

I always document my Python code with numpydoc style docstrings. For my private projects, I also generate the documentation as HTML and host them. That is super helpful because this way I can Google it easily.

For my company, I didn't generate it and of course I didn't host it publicly.

If documentation can't be hosted publicly and is only used within the team, is there any value of hosting it in private?

If there is none, is there any use of generating the documentation instead of just having a readme, some markdown files in doc/ and, of course, the docstrings?

Improve this question
4
  • 1
    Who is the audience of this documentation - just you and your team? What is their preferred form of reading it? Ask them, and you have your answer.
    – Doc Brown
    Aug 10, 2019 at 9:19
  • The prefered audience is my team. This includes people that are not even hired yet. Hence I cannot ask them. But even if it was just for people I know, one reason to ask for best practice here is because I / my team might miss something / be not aware of a super useful workflow.
    – Martin Thoma
    Aug 10, 2019 at 9:56
  • People you have not hired yet are irrelevant for now, since they are currently not your audience. If you need a hosted doc later for someone new, you could set up it right when its needed. And different teams work differently, there is nothing like a universally accepted "best practice" for the working culture in teams - you have to find out what works best for your team.
    – Doc Brown
    Aug 10, 2019 at 10:20
  • 1
    Documentation can also be exported for applications like Dash or similar docs viewer. Documentation is also easier to navigate for engineers who are not familiar with the code base.
    – Shane Hsu
    Aug 10, 2019 at 10:24

1 Answer 1

Reset to default
4

While you can't Google it, you can still search it. Yes, I know, most search systems can hardly be compared to Google, but they are still better than nothing.

You can, of course, search the code source as well. But documentation embedded in code source doesn't have the same purpose as the same documentation presented in a form of standalone document.

  • The former is used when working on a particular piece of code (i.e. I want to call that method, but I'm wondering if I can pass null to its second parameter and what exceptions should I catch).

  • The later is used in a more general context of exploring the project.

But, more importantly, be pragmatic. It takes a few minutes to host the documentation internally, so do it. Advertise it among your peers. And, later on, check the statistics. If over a month, the number of persons who visited the website is close to zero, it's a good sign that either nobody cares, or the documentation quality is not that good or you haven't advertised your site enough.

Improve this answer
0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.