What project's documentation is your favorite?

[Ralph Bean]

Our documentation is not that great. It's better than it was, but it could do with a little restructuring as we expand on it. I'm missing a vision though for what "great docs" looks like, and I'm looking for inspiration.

Is there a project (or product) out there that you use where you just love the docs?

[Maneesh Mehra]

I asked my favorite AI tool and this is what it told me:

There isn’t a single definitive answer to which software documentation is "the best in the world," as this can be subjective and context-dependent. However, several organizations and projects are often praised for having excellent documentation due to their clarity, structure, and comprehensiveness. Here are a few notable ones:

1. GitHub

• Why it’s praised: GitHub's documentation is known for being clean, easy to navigate, and accessible for developers at all levels. Their extensive use of markdown, alongside clear examples and community-contributed content, helps developers understand both basic and advanced concepts.
• Example: GitHub Docs

2. Stripe

• Why it’s praised: Stripe’s API documentation is consistently lauded for being user-friendly, detailed, and intuitive. They focus on providing a quick-start guide and a comprehensive set of examples that help developers integrate payment solutions with minimal friction.
• Example: Stripe Docs

3. Postman

• Why it’s praised: Postman has one of the best API documentation systems available. They emphasize clarity and visual aids (like examples and interactive tools) to make their documentation accessible and easy to follow.
• Example: Postman Docs

4. Mozilla Developer Network (MDN)

• Why it’s praised: The MDN Web Docs is often considered the gold standard for web development documentation. It is thorough, highly detailed, and regularly updated. It offers everything from beginner tutorials to advanced references on HTML, CSS, JavaScript, and web APIs.
• Example: MDN Web Docs

5. Microsoft (especially .NET and Azure)

• Why it’s praised: Microsoft has a comprehensive and highly structured documentation system, particularly for its .NET framework, Azure cloud services, and other enterprise-level technologies. The documentation is often accompanied by practical examples, use cases, and clear navigation.
• Example: .NET Docs, Azure Docs

6. Kubernetes

• Why it’s praised: The Kubernetes documentation is highly detailed, well-organized, and continuously improved. It’s particularly strong in explaining complex concepts related to container orchestration, and it includes a variety of tutorials, conceptual overviews, and task-oriented guides.
• Example: Kubernetes Docs

7. Docker

• Why it’s praised: Docker’s documentation is known for being beginner-friendly, yet thorough. It explains complex concepts in a digestible manner and provides a lot of real-world examples to help developers get started quickly.
• Example: Docker Docs

8. Google Cloud

• Why it’s praised: Google’s cloud services documentation is detailed, well-organized, and often provides interactive tutorials and code samples. It’s particularly useful for developers building on Google Cloud Platform.
• Example: Google Cloud Docs

9. Twilio

• Why it’s praised: Twilio is known for its developer-friendly documentation. It provides clear, easy-to-follow instructions for integrating communication services like SMS, voice, and video into applications. Their use of code snippets and step-by-step guides makes it accessible for developers.
• Example: Twilio Docs

10. Rails (Ruby on Rails)

• Why it’s praised: The Rails documentation has long been celebrated for its thoroughness and developer-first focus. It offers a mix of tutorials, guides, and API references to cater to developers of various skill levels.
• Example: Rails Guides

Key Attributes of Excellent Documentation:

• Clarity: Documentation should be easy to read and understand, even for beginners.
• Structure: Well-organized and easy to navigate, with logical grouping of topics.
• Comprehensiveness: Covers a broad range of topics, from basic installation and configuration to advanced troubleshooting.
• Interactivity: Code examples and live demos are often included to make learning more engaging.
• Consistency: Uses consistent terminology, formatting, and naming conventions.
• Up-to-date: Regularly updated to reflect changes in the software or technology.

While these examples are widely regarded as having excellent documentation, "best" will always depend on the context—whether you’re a beginner, an expert, or somewhere in between, your needs from documentation might differ.

Thanks,

Maneesh Mehra

He / Him / His

MANAGER - cONTAINER SERVICES (CVP, IIB)

314 Littleton Road, Westford, Massachusetts, USA

mme...@redhat.com

Please Note: I may be sending this outside normal business hours. It is by choice and I don't expect anyone to respond to this message outside their business hours.   

On Mon, Jan 13, 2025 at 4:25 PM Ralph Bean <rb...@redhat.com> wrote:

Our documentation is not that great. It's better than it was, but it could do with a little restructuring as we expand on it. I'm missing a vision though for what "great docs" looks like, and I'm looking for inspiration.

Is there a project (or product) out there that you use where you just love the docs?

--
You received this message because you are subscribed to the Google Groups "Konflux CI" group.
To unsubscribe from this group and stop receiving emails from it, send an email to konflux+u...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/konflux/CAGq%2BFfxyFBT1GxRD7taCYjHRMQ%2BVMxA-YCUnnoXxwO-eBXmWvg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Adam Kaplan]

I will vouch for Stripe, especially their REST API docs. A decade ago I was using those extensively to overhaul the payments module at my job (pre Red Hat).

I also used to contribute to Kubernetes docs. SIG-Docs is very intentional about how content is organized, structured, and planned. I want to say the prior chair of committee (Celeste Hogan) wrote and presented quite a bit of material on how the group operated.

To view this discussion visit https://groups.google.com/d/msgid/konflux/CANC18PbqeS8qzARdhJvzYpOUWEf%3DEfyfy45vVVRFrkCDSGYPSA%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Adam Kaplan

He/Him

Principal Software Engineer

Red Hat

100 E. Davie Street

adam....@redhat.com    

[Chmouel Boudjnah]

The best documentation is the one where i have the source to be able
to grep to!

It's always up to date...

(i may be in the minority)

On Mon, Jan 13, 2025 at 10:25 PM Ralph Bean <rb...@redhat.com> wrote:
>
> Our documentation is not that great. It's better than it was, but it could do with a little restructuring as we expand on it. I'm missing a vision though for what "great docs" looks like, and I'm looking for inspiration.
>
> Is there a project (or product) out there that you use where you just love the docs?
>

[Ken Dreyer]

When I was going through the Konflux User enablement session here in Raleigh (really helpful by the way - thanks to everyone who set that up!), the biggest thing I would change about Konflux docs is to add a very clear "Red Hat" style banner to the top of our internal documentation so it's simple to tell at a glance what I'm reading.

https://konflux-ci.dev/docs/ lack some very critical information about how to get started using Red Hat's production Konflux deployment.

Red Hat's "downstream" documentation is layered on top of this, and it is much more useful: https://konflux.pages.redhat.com/docs/users/getting-started/getting-access.html 

Unfortunately these two websites' headers and visuals appear identical, so it's difficult to tell at a glance if I'm reading the useful Red Hat site or the sanitized upstream site. I had many mental double-takes, like "I'm sure I saw such-and-such somewhere in the docs" and only realized that they were two completely different websites halfway through the first onboarding day.

On Mon, Jan 13, 2025 at 4:25 PM Ralph Bean <rb...@redhat.com> wrote:

Our documentation is not that great. It's better than it was, but it could do with a little restructuring as we expand on it. I'm missing a vision though for what "great docs" looks like, and I'm looking for inspiration.

Is there a project (or product) out there that you use where you just love the docs?

--

[Adam Kaplan]

Yesterday I had an excellent conversation with Nate Waddington, the lead for tech docs at the CNCF as well as their mentorship program. He pointed me to several resources that I think are relevant to this thread:

1. The CNCF has a "docs primer" aimed at sandbox projects, but is relevant to any open source project [1].

2. The Linux Foundation has free online courses for technical writing, aimed at open source maintainers [2][3].

3. The "Docs for Developers" book is highly recommended reading [4]. Its guidelines heavily influence how the CNCF evaluates projects that ask for docs support/improvement.

[1] https://github.com/cncf/techdocs/blob/main/docs/sandbox-doc-primer.md

[2] https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc111/

[3] https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/

[4] https://docsfordevelopers.com/

To view this discussion visit https://groups.google.com/d/msgid/konflux/CALqRxCyUP19WmmU3g6pbbmaWbZXfK6pkJ6T3kst8b2ugOCeACw%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

[Assaf Rodriguez]

Thank you for this question!

I found that I am missing and wish to have a diagram/map of all the moving parts and their relations, and their team owners.

Something similar to the "Release Train" we had for the classic Release Pipeline we have today. 

Something that I can present to any engineer or newcomer so I can explain 'with my hands' or my 'mouse pointer' and talk about its flow when needed.

(Maybe something similar to this one)

Assaf R

On Mon, 13 Jan 2025 at 23:25, Ralph Bean <rb...@redhat.com> wrote:

Our documentation is not that great. It's better than it was, but it could do with a little restructuring as we expand on it. I'm missing a vision though for what "great docs" looks like, and I'm looking for inspiration.

Is there a project (or product) out there that you use where you just love the docs?

--