What advantages are there to having a project-specific website for documentation?

Question

As a software engineer I often interact with documentation for software projects across the Internet, in particular on GitHub which provides methods for documenting your project. Anecdotally, it seems like more projects are using GitHub's built-in documentation nowadays but many projects, especially popular ones, often have their own dedicated website, which effectively just offer documentation and download links, the same as GitHub.

While on one hand I think having a separate website adds a level of legitimacy to the project or the ability to fully customize the styling, but the overhead in creating such a website seems cost-prohibitive, at least at face value.

I feel like I've seen this in other contexts as well, where documentation that could have just been built into a standard system is instead partition off to a separate website and linked to from the expected location.

Are there other perceived advantages to this approach from a communication perspective? Is there maybe an advantage to having your documentation in a space that is free of other context? Are there any disadvantages to this approach?

Answer 1

It depends on what the project is and if it is related to other projects by the same group.

If it is a small, single project, it may not be worth creating a dedicated website because it is simple enough to follow a more informal documentation scheme such as a README file or even something similar to man pages.

If it is a large project, it would definitely benefit from a proper documentation website that contains subject explanations, reference material, tutorials, etc.

When there are multiple projects, I would argue that it is best for the docs to be coherently organized on a single website (whether or not that is the actual underlying architecture). This has the following advantages:

• It promotes the related projects within the organization and, if there is branding involved, promotes the organization.
• It sets the stage for adding documentation for other projects that may be developed.
• It is easier to maintain documentation items such as cross-references, broken links, outdated material, review cycles, content organization, styling, tagging, SEO, etc.

There would definitely be increased costs associated with this, so the organization would need to determine if this is a cost-effective strategy for them.