# Documentation Has Different Meanings and Requires Context-Specific Practices

DevFeed: [Documentation Has Different Meanings and Requires Context-Specific Practices](<https://devfeed.tech/articles/what-do-you-mean-documentation-30950.md>)

Original publisher: [Read original article](<https://www.doctave.com/blog/what-do-you-mean-documentation>)

Author: Niklas Begley

Published: 2023-10-17T07:00:00Z

Content type: opinion

Language: en

Sources: [Doctave - Build beautiful developer portals with docs-as-code](<https://devfeed.tech/sources/doctave-build-beautiful-developer-portals-with-docs-as-code.md>)

Topics: [Documentation](<https://devfeed.tech/topics/documentation.md>), [Development](<https://devfeed.tech/topics/development.md>), [code comments](<https://devfeed.tech/topics/code-comments.md>), [API](<https://devfeed.tech/topics/api.md>), [Markdown](<https://devfeed.tech/topics/markdown.md>), [toolchain](<https://devfeed.tech/topics/toolchain.md>)

Tags: [api](<https://devfeed.tech/tags/api.md>), [best-practices](<https://devfeed.tech/tags/best-practices.md>), [blog](<https://devfeed.tech/tags/blog.md>), [code-comments](<https://devfeed.tech/tags/code-comments.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [markdown](<https://devfeed.tech/tags/markdown.md>), [technical-documentation](<https://devfeed.tech/tags/technical-documentation.md>), [toolchain](<https://devfeed.tech/tags/toolchain.md>)

## AI overview

The article argues that "documentation" can refer to different materials, from README files and code comments to developer portals, manuals, and API references. Because these forms serve different audiences and contexts, advice to reduce or replace documentation with automation cannot be applied universally.

## Source excerpt

There was a post submitted to the Orange Website™ the other week with the title "Delete half your documentation" (HN thread here). The author talks about how documentation inherently has a cost, and how we should minimize the amount of documentation we need. It becomes outdated, requires maintenance, and "nobody reads it anyway". Instead, they argue, we should use type annotations, tested examples, and other methods to remove the requirement for manually maintaining documentation. Some of these arguments have some merits in the right context. But what really caught my eye in the post was this line: "When I say 'documentation', I mean all forms of it, including README, Markdown files, docstrings, and code comments." Hang on. This is not all forms of documentation! And we certainly cannot apply these rules universally. Documentation is in the eyes of the reader I recently Tweeted about the confusion that can happen when people use the word "documentation" to refer to different things. The word "documentation" has so many meanings depending on who you're talking to. To one person it's a single README file. To another, it's a full blown dev portal with guides and API references. Causes legitimate confusion sometimes -- Niklas Begley (@NiklasBegley) September 6, 2023 The post mentioned above is a great example of this phenomenon. The author clearly had the view that "documentation" means code documentation: docstrings, and other supplementing information you can include in or generate from raw source code. This is quite natural for software developers, since it's the kind of documentation they are used to producing themselves. And for their case, perhaps relying on automation over prose to ensure your documentation is in order is a good idea. But what about developer portals, manuals, or API references? Surely a technical writer documenting a complex developer toolchain should not apply the same thinking and "delete half their documentation"? An overloaded term Technical