[Draft] New Developer Documentation Infrastructure Proposal (Replacing Wiki?) #105348

New Issue

Julian Eisel · 2023-03-01T17:59:02+01:00

Julian Eisel commented

2023-03-01 17:59:02 +01:00

This task looks at the infrastructure for technical documentation. This seems crucial for the goal of improving the technical documentation culture for Blender, so that developers write, maintain and use technical documentation as part of their every day life.

To achieve that, the proposed platform uses developer centric tooling. Technical documentation is moved close to the code and uses the same workflow ("docs-as-code"). Other big organizations claim this had a major positive impact on their documentation culture.

More specifically the proposal is a Git repository with Markdown files, which can be generated into static HTML using MkDocs or Material for MkDocs.

Motivation

Generally the technical documentation for Blender is lacking, it does not receive enough attention. This is the main motivation behind attempting to improve the technical documentation culture.

There are a number of issues with the current infrastructure, and various opportunities.

Developers expressed dissatisfaction with the Wiki writing experience. The syntax is weird, formatting is limited and finicky, media management is a hassle, they don't enjoy working on a separate website with separate login, etc.
Search-ability, discoverability and navigation aren't great. For some things you kinda need to know that they are there (e.g. setup for commit access, ASan, etc). It's not too bad though.
Opportunity: Rethink how developer documentation is presented/structured. Instead of loose pages about individual components, present guided paths for an area of Blender (animation system, asset system, core data management, etc).
A developer handbook could include all general information, with all the important stuff upfront (build instructions, guidelines, important tools, testing), less crucial stuff in the back (unity builds, bisecting with event simulation, etc) [TODO create a task on developer handbook]).
Opportunity: Make writing technical documentation something developers enjoy doing: Docs-as-code, good integration with code repositories, better tooling, ...
Opportunity: More modern feeling documentation output with modern features. "Last Updated" hints, generate diagrams from textual descriptions, mathematical typesetting, tags, nicer landing page, dark mode, button to copy code snippets, custom icons, foldable sections, ...

Docs-As-Code (or docs-like-code)

Various big organizations have switched to a Docs Like Code infrastructure (e.g. Google, Microsoft, Spotify, Twitter, ...), using a similar technology stack (Markdown + Git, typically using MkDocs). They claim that this "solved" the big issues they had with technical documentation, and brought major improvements for their documentation and overall engineering culture. [TODO references]

Some of the benefits of docs like code are:

Documentation lives close to code.
Fully fledged, familiar version control.
Use an IDE to write docs.
CI/CD for docs.
"Code" review for docs.
Tasks and reports for docs.

(Material for) MkDocs

MkDocs and Material for MkDocs are well known, established projects enabling a Docs Like Code workflow using Markdown and Git. The resulting documentation is enjoyable to work with, and so is the writing workflow.

Some practical benefits:

Markdown is a language developers are familiar with (used by Github, Gitea, Phabricator, blender.chat, devtalk, HackMD, ...)
Gitea (and other forges) support editing Markdown with live previewing.
Git repository integration (e.g. "Edit" button opening the markdown file on Github, Gitlab, etc)
Great local WYSIWYG live editing workflow (open a browser window that auto-refreshes as source files are saved)
Syntaxes to generate diagrams from within markdown files.
Good builtin search.
Multiple themes, including bundled light and dark themes.
Great customization.

Does this replace the Wiki?

With the developer documentation moved out of the Wiki, one of the main purposes for the Wiki is gone. Rather than introducing yet another platform, it's better to see if the Wiki can be "removed" entirely.

Where should the release notes go?
Where should the personal pages go (especially the weekly reports).
Where should the Human Interface Guidelines go?
How to handle the gigabytes of attachments (images, videos, .blend files, etc)
Archive the wiki?

MkDocs or Sphinx?

The Blender manual uses Sphinx, and it's a fine framework. However, feedback from developers is that they don't enjoy working with it much, mostly because ReStructuredText is a rather unfamiliar syntax for them. Markdown is very common even outside of Blender, and used across most Blender development platforms. This familiarity seems important to minimize the barrier of entry for developers writing documentation. Gitea supports Markdown with live-preview, but not ReStructuredText (which some have considered crucial). Otherwise there doesn't seem to be much of a difference in functionality, both are greatly extensible through extensions and plugins (could be investigated and elaborated on further).

There is an extention to use Markdown within Sphinx, but mixing markup languages seems weak, and we'll end up converting files between languages. Rather make a choice and stick to it. This could still be investigated further.

This task looks at the infrastructure for technical documentation. This seems crucial for the goal of improving the technical documentation culture for Blender, so that developers write, maintain and use technical documentation as part of their every day life. To achieve that, the proposed platform uses developer centric tooling. Technical documentation is moved close to the code and uses the same workflow ("docs-as-code"). Other big organizations claim this had a major positive impact on their documentation culture. More specifically the proposal is a Git repository with Markdown files, which can be generated into static HTML using [MkDocs](https://www.mkdocs.org/) or [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). ## Motivation Generally the technical documentation for Blender is lacking, it does not receive enough attention. This is the main motivation behind attempting to improve the technical documentation culture. There are a number of issues with the current infrastructure, and various opportunities. * Developers expressed dissatisfaction with the Wiki writing experience. The syntax is weird, formatting is limited and finicky, media management is a hassle, they don't enjoy working on a separate website with separate login, etc. * Search-ability, discoverability and navigation aren't great. For some things you kinda need to know that they are there (e.g. setup for commit access, ASan, etc). It's not *too* bad though. * **Opportunity**: Rethink how developer documentation is presented/structured. Instead of loose pages about individual components, present guided paths for an area of Blender (animation system, asset system, core data management, etc). A developer handbook could include all general information, with all the important stuff upfront (build instructions, guidelines, important tools, testing), less crucial stuff in the back (unity builds, bisecting with event simulation, etc) [TODO create a task on developer handbook]). * **Opportunity**: Make writing technical documentation something developers enjoy doing: Docs-as-code, good integration with code repositories, better tooling, ... * **Opportunity**: More modern feeling documentation output with modern features. "Last Updated" hints, generate diagrams from textual descriptions, mathematical typesetting, tags, nicer landing page, dark mode, button to copy code snippets, custom icons, foldable sections, ... ## Docs-As-Code (or docs-like-code) Various big organizations have switched to a Docs Like Code infrastructure (e.g. Google, Microsoft, Spotify, Twitter, ...), using a similar technology stack (Markdown + Git, typically using MkDocs). They claim that this "solved" the big issues they had with technical documentation, and brought major improvements for their documentation and overall engineering culture. [TODO references] Some of the benefits of docs like code are: - Documentation lives close to code. - Fully fledged, familiar version control. - Use an IDE to write docs. - CI/CD for docs. - "Code" review for docs. - Tasks and reports for docs. ## (Material for) MkDocs [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) are well known, established projects enabling a Docs Like Code workflow using Markdown and Git. The resulting documentation is enjoyable to work with, and so is the writing workflow. Some practical benefits: - Markdown is a language developers are familiar with (used by Github, Gitea, Phabricator, blender.chat, devtalk, HackMD, ...) - Gitea (and other forges) support editing Markdown with live previewing. - Git repository integration (e.g. "Edit" button opening the markdown file on Github, Gitlab, etc) - Great local WYSIWYG live editing workflow (open a browser window that auto-refreshes as source files are saved) - Syntaxes to generate diagrams from within markdown files. - Good builtin search. - Multiple themes, including bundled light and dark themes. - Great customization. ## Does this replace the Wiki? With the developer documentation moved out of the Wiki, one of the main purposes for the Wiki is gone. Rather than introducing yet another platform, it's better to see if the Wiki can be "removed" entirely. - Where should the release notes go? - Where should the personal pages go (especially the weekly reports). - Where should the Human Interface Guidelines go? - How to handle the gigabytes of attachments (images, videos, .blend files, etc) - Archive the wiki? ## MkDocs or Sphinx? The Blender manual uses Sphinx, and it's a fine framework. However, feedback from developers is that they don't enjoy working with it much, mostly because ReStructuredText is a rather unfamiliar syntax for them. Markdown is very common even outside of Blender, and used across most Blender development platforms. This familiarity seems important to minimize the barrier of entry for developers writing documentation. Gitea supports Markdown with live-preview, but not ReStructuredText (which some have considered crucial). Otherwise there doesn't seem to be much of a difference in functionality, both are greatly extensible through extensions and plugins (could be investigated and elaborated on further). There is an [extention to use Markdown within Sphinx](https://www.sphinx-doc.org/en/master/usage/markdown.html#markdown), but mixing markup languages seems weak, and we'll end up converting files between languages. Rather make a choice and stick to it. This could still be investigated further.

Julian Eisel added the

Type

Design

label 2023-03-01 17:59:02 +01:00

Julian Eisel added this to the Technical Documentation project 2023-03-01 17:59:03 +01:00

Ray molenkamp closed this issue

2023-03-01 18:07:16 +01:00

Blender Bot added the

Status

Archived

label 2023-03-01 18:07:17 +01:00

Ray molenkamp reopened this issue

2023-03-01 18:13:23 +01:00

Blender Bot added

and removed

labels 2023-03-01 18:13:24 +01:00

Julian Eisel changed title from ~~New Developer Documentation Infrastructure (replacing Wiki?)~~ to Proposal Draft: New Developer Documentation Infrastructure (replacing Wiki?)

2023-03-01 18:14:48 +01:00

Julian Eisel changed title from ~~Proposal Draft: New Developer Documentation Infrastructure (replacing Wiki?)~~ to [Draft] New Developer Documentation Infrastructure Proposal (Replacing Wiki?)

2023-03-01 18:15:06 +01:00

Brecht Van Lommel commented

2023-03-01 18:56:38 +01:00

Where should the release notes go?

These are mostly written by developers, and if they prefer markdown it seems logical to use it here as well.

Where should the personal pages go (especially the weekly reports).

As you suggested to me earlier, this could move to a repository on projects.blender.org for every user, e.g. projects.blender.org/brecht/weekly-reports. Gitea can render markdown and for this purpose it seems good enough, no need for MkDocs.

Where should the Human Interface Guidelines go?

This definitely belongs in the developer docs I think.

How to handle the gigabytes of attachements (images, videos, .blend files, etc)

Perhaps a solution here would be to make a branch for every release, and merge it all together for publishing? That way a checkout could still have a reasonable size if the big files are in LFS.

> Where should the release notes go? These are mostly written by developers, and if they prefer markdown it seems logical to use it here as well. > Where should the personal pages go (especially the weekly reports). As you suggested to me earlier, this could move to a repository on projects.blender.org for every user, e.g. `projects.blender.org/brecht/weekly-reports`. Gitea can render markdown and for this purpose it seems good enough, no need for MkDocs. > Where should the Human Interface Guidelines go? This definitely belongs in the developer docs I think. > How to handle the gigabytes of attachements (images, videos, .blend files, etc) Perhaps a solution here would be to make a branch for every release, and merge it all together for publishing? That way a checkout could still have a reasonable size if the big files are in LFS.

👍 1

Campbell Barton commented

2023-03-15 04:33:44 +01:00

+1 for using Gitea's markdown formatting directly (without MkDocs) - noting against MkDocs, it's just another tool to have to setup locally / as part of our infrastructure. There will likely be subtle differences python-markdown & goldmark (used by MkDocs and Gitea respectively) and having to be aware of all this adds some additional burden.

Personally I'd be happy to use Sphinx/RST for developer docs, although I can't argue that markdown is now more popular for developers.

+1 for using Gitea's markdown formatting directly (without MkDocs) - noting against MkDocs, it's just another tool to have to setup locally / as part of our infrastructure. There will likely be subtle differences python-markdown & goldmark (used by MkDocs and Gitea respectively) and having to be aware of all this adds some additional burden. --- Personally I'd be happy to use Sphinx/RST for developer docs, although I can't argue that markdown is now more popular for developers.

Brecht Van Lommel commented

2023-03-16 00:50:00 +01:00

Gitea doesn't offer good navigation or any search for docs. To me it seems necessary to publish the developer docs to a website for better presentation. Especially for more user facing things like build instructions and release notes.

I agree the difference in markdown dialect and extensions between Gitea and MkDocs will cause friction though.

We could perhaps support previewing MkDocs markdown on Gitea similar to what we plan to do for RST for the manual (infrastructure/blender-projects-platform#51). Though the way that currently works, there are still differences to be aware of.

Gitea doesn't offer good navigation or any search for docs. To me it seems necessary to publish the developer docs to a website for better presentation. Especially for more user facing things like build instructions and release notes. I agree the difference in markdown dialect and extensions between Gitea and MkDocs will cause friction though. We could perhaps support previewing MkDocs markdown on Gitea similar to what we plan to do for RST for the manual (infrastructure/blender-projects-platform#51). Though the way that currently works, there are still differences to be aware of.

Campbell Barton commented

2023-03-22 01:48:43 +01:00

In this case I'd much prefer to use Sphinx/RST. Developers already need to use this for the user-manual. We know how to write extensions for this system and it it avoids introducing yet-another technology to have to become familier with (when we already have quite a few if you count Sphinx/MediaWiki/Doxygen/Gitea).

Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference.

One other point is that the markdown used in Devtalk/Gitea is liteweight - some rich text and a few conventions for dot-points, literal text and so on.

The kind of markup we'll need for larger more structured document requires inter-linking sections - conventions for referencing commits/issues/PR's, this will be something people will have to learn and document in it's self.

While I'm noting some down-sides with the proposal, I'd expect we could move from the Wiki to Sphinx/MkDocs and both would work out well enough. Nevertheless, noting my preference here - it may well be that markdown is a more popular choice for others.

In this case I'd much prefer to use Sphinx/RST. Developers already need to use this for the user-manual. We know how to write extensions for this system and it it avoids introducing yet-another technology to have to become familier with (when we already have quite a few if you count Sphinx/MediaWiki/Doxygen/Gitea). Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference. One other point is that the markdown used in Devtalk/Gitea is liteweight - some rich text and a few conventions for dot-points, literal text and so on. The kind of markup we'll need for larger more structured document requires inter-linking sections - conventions for referencing commits/issues/PR's, this will be something people will have to learn and document in it's self. ---- While I'm noting some down-sides with the proposal, I'd expect we could move from the Wiki to Sphinx/MkDocs and both would work out well enough. Nevertheless, noting my preference here - it may well be that markdown is a more popular choice for others.

Brecht Van Lommel commented

2023-03-22 15:47:25 +01:00

Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference.

That's what I thought too. For me also mediawiki syntax is not an impediment. But other developers say they dislike it to the point of it discouraging writing dev docs at all.

Personally I find markdown more pleasant to write, but don't feel very strongly about it. So other developers are probably in a better position to make the case for that.

> Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference. That's what I thought too. For me also mediawiki syntax is not an impediment. But other developers say they dislike it to the point of it discouraging writing dev docs at all. Personally I find markdown more pleasant to write, but don't feel very strongly about it. So other developers are probably in a better position to make the case for that.

Campbell Barton referenced this issue

2023-04-11 09:45:55 +02:00

Error at 'Building Blender on Ubuntu' page #106747

Julian Eisel commented

2023-05-10 20:32:09 +02:00

For me Markdown (together with a generator like MkDocs and the extentions it provides) is clearly the preferable choice. Some points for it:

The obvious one: More widely adopted & better known. Important to make it easy for devs to start writing.
Widely supported by editors/IDEs, with great tooling (like live preview in VSCode).
Same as on other blender.org platforms (projects.blender.org, devtalk, chat) - albeit flavors differ, and use-cases simpler.
Pleasant to write, arguably much more so than reStructuredText (IMO a quite crucial point).
Live editing previews supported on Gitea out-of-the-box, no custom renderer needed.
Plenty of devs already use HackMD (markdown based) for collaborative editing of docs/notes. Reformatting to move to the official docs is a hassle.
Supported by a range site generators (MkDocs, VitePress, Docusaurus, ...) and we can switch quite easily. Useful since we don't have to make a final decision yet.
Supported within Doxygen.

Personally, I find the writing experience with Material for MkDocs very pleasant. It just makes it very easy to produce quality, feature rich & great looking documentation out of the box. My experiences with Sphinx have been quite far from that. Although I see why it makes a lot more sense in a Python context of course.

I'm also looking some more into vitepress as alternative to MkDocs (markdown too). The Blender Studio started using this for documentation, and it seems quite promising.

For me Markdown (together with a generator like MkDocs and the extentions it provides) is clearly the preferable choice. Some points for it: - The obvious one: More widely adopted & better known. Important to make it easy for devs to start writing. - Widely supported by editors/IDEs, with great tooling (like live preview in VSCode). - Same as on other blender.org platforms (projects.blender.org, devtalk, chat) - albeit flavors differ, and use-cases simpler. - Pleasant to write, arguably much more so than reStructuredText (IMO a quite crucial point). - Live editing previews supported on Gitea out-of-the-box, no custom renderer needed. - Plenty of devs already use HackMD (markdown based) for collaborative editing of docs/notes. Reformatting to move to the official docs is a hassle. - Supported by a range site generators (MkDocs, VitePress, Docusaurus, ...) and we can switch quite easily. Useful since we don't have to make a final decision yet. - Supported [within Doxygen](https://www.doxygen.nl/manual/markdown.html). Personally, I find the writing experience with Material for MkDocs very pleasant. It just makes it very easy to produce quality, feature rich & great looking documentation out of the box. My experiences with Sphinx have been quite far from that. Although I see why it makes a lot more sense in a Python context of course. I'm also looking some more into [vitepress](https://vitepress.dev/) as alternative to MkDocs (markdown too). The Blender Studio started using this for documentation, and it seems quite promising.

Julian Eisel commented

2023-05-10 20:38:23 +02:00

Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference.

I'd disagree, I think the technology used can have a large impact on the technical writing culture. If we want devs to work on documentation regularly, we need to make it as pleasant as possible for them.

Case in point, Google, Twitter and Spotify have moved to a "docs as code" approach and claim it completely changed their technical documentation culture. Great summary: https://www.doctave.com/blog/2021/09/07/how-google-twitter-and-spotify-build-culture-of-documentation.html (Although I find the intro text makes a different point than the rest of the article.)

As a note, @Jeroen-Bakker, @JacquesLucke and @filedescriptor have started contributing documentation in my devdocs repository. This should help us get feedback. We're also looking into setting up buildbots and servers to build & host the docs entirely on blender.org, shouldn't take long.

> Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference. I'd disagree, I think the technology used can have a large impact on the technical writing culture. If we want devs to work on documentation regularly, we need to make it as pleasant as possible for them. Case in point, Google, Twitter and Spotify have moved to a "docs as code" approach and claim it completely changed their technical documentation culture. Great summary: https://www.doctave.com/blog/2021/09/07/how-google-twitter-and-spotify-build-culture-of-documentation.html (Although I find the intro text makes a different point than the rest of the article.) --- As a note, @Jeroen-Bakker, @JacquesLucke and @filedescriptor have started contributing documentation [in my devdocs repository](https://projects.blender.org/JulianEisel/devdocs). This should help us get feedback. We're also looking into setting up buildbots and servers to build & host the docs entirely on blender.org, shouldn't take long.

Julian Eisel commented

2023-05-10 20:52:21 +02:00

Here's some content written by @Jeroen-Bakker, as a live demo: https://julianeisel.github.io/devdocs/eevee_and_viewport/gpu/
Feel free to browse around some more, but most pages are dummies.

Here's some content written by @Jeroen-Bakker, as a live demo: https://julianeisel.github.io/devdocs/eevee_and_viewport/gpu/ Feel free to browse around some more, but most pages are dummies.

Jeroen Bakker commented

2023-05-11 09:46:33 +02:00

I do think that we should consider different aspects of documentation and the audience (both writers and readers). If only considering writing documentation media-wiki is fine. But looking at the diversity of our reading audience, or involvement it might not be the case.

Documentation (similar) to code is that you (should) write it once, but read it many times. Although looking at the core-devs I believe they don't mind writing it using media-wiki.
Looking at the (younger) reading audience they aren't able to read long pages of text. This is a world-wide phenomenon that we should consider. Write shorter paragrams, or use more 'read-more...' include diagrams for visual organized brains.
I use tools like plantUML/mermaid to add small diagrams to the documentation. In the current setup of media wiki this introduces an overhead as the diagrams needs to be uploaded as images. This could be solved with installing media wiki extensions like https://www.mediawiki.org/wiki/Extension:Mermaid.
Documentation is like code and version control can help with organizing and traceability. I find it hard to use the media-wiki version control as it is page/file oriented. Organizing them in commits can help understanding where changes needs to happen.
Enable refactorings in documentation, cleanups etc.
Removing burdens would increase involvement from community. Especially when looking at involvement programs like summer of docs etc.
Pleasant to read (customizability), reading accessibility tools etc would be nice to have to make sure that we don't focus on certain audiences/cultures.

So for writing it might not matter that much, but for reading, the reason why we are writing documentation, it does. I believe that selecting the right tool, use different writing styles, would increase involvement not only in the documentation area.

I do think that we should consider different aspects of documentation and the audience (both writers and readers). If only considering writing documentation media-wiki is fine. But looking at the diversity of our reading audience, or involvement it might not be the case. * Documentation (similar) to code is that you (should) write it once, but read it many times. Although looking at the core-devs I believe they don't mind writing it using media-wiki. * Looking at the (younger) reading audience they aren't able to read long pages of text. This is a world-wide phenomenon that we should consider. Write shorter paragrams, or use more 'read-more...' include diagrams for visual organized brains. * I use tools like plantUML/mermaid to add small diagrams to the documentation. In the current setup of media wiki this introduces an overhead as the diagrams needs to be uploaded as images. This could be solved with installing media wiki extensions like https://www.mediawiki.org/wiki/Extension:Mermaid. * Documentation is like code and version control can help with organizing and traceability. I find it hard to use the media-wiki version control as it is page/file oriented. Organizing them in commits can help understanding where changes needs to happen. * Enable refactorings in documentation, cleanups etc. * Removing burdens would increase involvement from community. Especially when looking at involvement programs like summer of docs etc. * Pleasant to read (customizability), reading accessibility tools etc would be nice to have to make sure that we don't focus on certain audiences/cultures. So for writing it might not matter that much, but for reading, the reason why we are writing documentation, it does. I believe that selecting the right tool, use different writing styles, would increase involvement not only in the documentation area.

👍 1

Campbell Barton commented

2023-05-12 05:22:20 +02:00

Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference.

I'd disagree, I think the technology used can have a large impact on the technical writing culture. If we want devs to work on documentation regularly, we need to make it as pleasant as possible for them.

For sure, but I disagree with the characterization as one system as great and everything else as unpleasant (although I personally have a strong preference for anything that can be edited locally and managed with version control).

Linux, Firefox, LLVM & CMake use Sphinx for their developer docs. Not to say this automatically means we should too - just pointing out other project have managed this and I don't see why we couldn't too, especially since it's already used for the User-Manual & Python API.

Case in point, Google, Twitter and Spotify have moved to a "docs as code" approach and claim it completely changed their technical documentation culture. Great summary: https://www.doctave.com/blog/2021/09/07/how-google-twitter-and-spotify-build-culture-of-documentation.html (Although I find the intro text makes a different point than the rest of the article.)

In general +1 for having docs closer to the code, I just don't see this as being isolated to a particular technology.

> > Developers prefer to write code than docs, so I'm not convinced the technology used will make a significant difference. > > I'd disagree, I think the technology used can have a large impact on the technical writing culture. If we want devs to work on documentation regularly, we need to make it as pleasant as possible for them. For sure, but I disagree with the characterization as one system as great and everything else as unpleasant _(although I personally have a strong preference for anything that can be edited locally and managed with version control)._ Linux, Firefox, LLVM & CMake use Sphinx for their developer docs. Not to say this automatically means we should too - just pointing out other project have managed this and I don't see why we couldn't too, especially since it's already used for the User-Manual & Python API. - https://www.kernel.org/doc/html/latest/process/development-process.html - https://firefox-source-docs.mozilla.org/testing/xpcshell/index.html - https://llvm.org/docs/CodingStandards.html - https://cmake.org/cmake/help/v3.26/manual/cmake-developer.7.html#cmake-domain > Case in point, Google, Twitter and Spotify have moved to a "docs as code" approach and claim it completely changed their technical documentation culture. Great summary: https://www.doctave.com/blog/2021/09/07/how-google-twitter-and-spotify-build-culture-of-documentation.html (Although I find the intro text makes a different point than the rest of the article.) In general +1 for having docs closer to the code, I just don't see this as being isolated to a particular technology.

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

[Draft] New Developer Documentation Infrastructure Proposal (Replacing Wiki?) #105348

Motivation

Docs-As-Code (or docs-like-code)

(Material for) MkDocs

Does this replace the Wiki?

MkDocs or Sphinx?