bell notificationshomepageloginNewPostedit profile

Topic : What advantages are there to having a project-specific website for documentation? As a software engineer I often interact with documentation for software projects across the Internet, in particular - selfpublishingguru.com

10.01% popularity

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?

Load Full (1)

Login to follow topic

More posts by @Hamaas631

Login to post a comment!

1 Comments

Sorted by latest first Latest Oldest Best

10% popularity

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.

Load Full (0)

Back to top