Developer-facing documentation and user-facing documentation – together or separate?

[jstasiak]

Hey,

I have one thing that's been bugging me recently. It's not entirely related to this documentation framework but there's an overlap and I'm hoping to get some good ideas here.

Say I have a Python/TS/Rust library that I want to document but it's not quite a homogeneous audience that I want to target with the documentation.

• I want a user/customer-facing documentation so that third parties can learn and understand how to use the library.
• I want a developer-facing documentation so that the existing developers and new developers can learn and understand how to develop and maintain the library.

These are the options I see:

1. Have one set of Tutorial/How-to/Reference/Explanations for them. In every section either
   a) Mix the user-facing and developer-facing content together
   b) Add some nesting so that How-to is split between developer-facing and user-facing parts
2. Keep the documentation separate – one set of Tutorial/How-to/Reference/Explanations for developer-facing, one set of Tutorial/How-to/Reference/Explanations for user-facing.

Which one would you pick and why? Any other options I haven't considered?

Any and all comments or suggestions welcome.

[jstasiak]

I've been revisiting this topic every now and then since I asked the question.

For what it's worth I think I prefer option 2 so far – one set of 4 sections for end-users, one set of 4 sections for developers.

The main reason for it is end-users won't care about the developer-facing documentation so less noise for them.

[drvinceknight]

I go for option 2 with nashpy (main docs: https://nashpy.readthedocs.io/en/stable/). I have a specific Contributor documentation which is a separate subsection of the main docs: https://nashpy.readthedocs.io/en/stable/contributing/index.html