Recommend external channel for generic recipes (articles, scripts) #8
Description
A documentation is related to a project. Anything that is not specific to the project should not be in the project's documentation.
It's a common practice to write down recipes in the documentation, so that collaborators can follow the recipe to perform some task. That's ok when the recipe is specific to the project. But when it is a general recipe, that's a bad idea. The writer had better reference an external ressource than embed it inside the project's documentation.
As an example:
- To deploy the project on a server, some network configuration has to be done on the server. Let's say it is some DHCP configuration.
- If no article (blog post, documentation...) exists about this operation, let's write and publish one.
- In case of DHCP configuration, I guess many ressources already exist.
- Then, in project's documentation, add an hyperlink to this external recipe.
Why?
- Think open-source: more contributors allows better quality.
- If it is not specific to project, it could be reused in other projects, by other people. So share it!
- Most of the time, an external ressource already exists... don't rewrite it. Spend your time on more valuable actions.
- If external ressource is incomplete or has issues, contribute!
- If no external ressource exists, let's create one! you may become famous :) In fact, you may attract contributors!