If it's nontechnical internal I'd lean towards confluence more. If it's technical external target read-the-docs or the JS equivalent. If you have a venture funded startup, the polish expectation is higher so maybe some type of built website. All of this should run through CI.
Google docs are too loose for my taste to serve as documentation, they are an 80% effort, good for collaboration with non-technical stakeholders, good for live writing but that shouldn't be the end artifact. Slack is also no place for documentation.
--
Here is what I'm targeting for my open source project targeted at technical users
Tutorials are used to walk users through using a project. I frequently use Jupyter notebooks for this and record a video walking through the notebook. The markdown portions are rough talking notes for my narration. The video ends up as a dead artifact, but some people learn better that way. The video is also a lower effort way for people to check out your project. [2] I try not to let perfect be the enemy of good for the videos especially.
I try to incorporate documentation into the development process. Many times I will start documenting a feature and realize it includes too many caveats, then I will redesign the feature so it's easier to document. Often this means that the tutorial comes first and is the only part built.
For API documentation ideally I will have a gallery that renders well, with executable examples that walk through options. Hardcoded small examples are key (avoid faker libraries and excessive scaffolding). React-edit-list has one of the best examples of this I have ever seen [1]
I like to write narrative documentation and sometimes link to the related PRs. The PRs should include the "Why" of the design decisions in their description. Narrative documentation should connect the "what" of API docs. Narrative documentation should also highlight recommended usage patterns.
If it's nontechnical internal I'd lean towards confluence more. If it's technical external target read-the-docs or the JS equivalent. If you have a venture funded startup, the polish expectation is higher so maybe some type of built website. All of this should run through CI.
Google docs are too loose for my taste to serve as documentation, they are an 80% effort, good for collaboration with non-technical stakeholders, good for live writing but that shouldn't be the end artifact. Slack is also no place for documentation.
--
Here is what I'm targeting for my open source project targeted at technical users
Tutorials are used to walk users through using a project. I frequently use Jupyter notebooks for this and record a video walking through the notebook. The markdown portions are rough talking notes for my narration. The video ends up as a dead artifact, but some people learn better that way. The video is also a lower effort way for people to check out your project. [2] I try not to let perfect be the enemy of good for the videos especially.
I try to incorporate documentation into the development process. Many times I will start documenting a feature and realize it includes too many caveats, then I will redesign the feature so it's easier to document. Often this means that the tutorial comes first and is the only part built.
For API documentation ideally I will have a gallery that renders well, with executable examples that walk through options. Hardcoded small examples are key (avoid faker libraries and excessive scaffolding). React-edit-list has one of the best examples of this I have ever seen [1]
I like to write narrative documentation and sometimes link to the related PRs. The PRs should include the "Why" of the design decisions in their description. Narrative documentation should connect the "what" of API docs. Narrative documentation should also highlight recommended usage patterns.
[1] https://mmomtchev.github.io/react-edit-list/#/simple
[2] https://www.youtube.com/watch?v=GPl6_9n31NE A walk through of how to extend a Jupyter notebook widget I wrote.