You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

First off, why document at all? The reasons are almost endless.

  • Less Dependence on Individuals. A project (or parts of a project) might rely too heavily on the technical knowledge of an individual, which can result on the downfall of a project once the individual graduates. Documentation ensures the knowledge is spread across the team and for future members, and is not lost throughout the years.
  • Central Source of Truth. Ensures everyone has a clear understanding of the projects goals, design, and implementations. 
  • Learning and Onboarding. Members undertaking new projects, or being introduced to SIPB, can refer to documentations to get up-to-speed on what we have been doing. There's less wasted time explaining every time from scratch how something, and – more importantly – new members gain important context that enables them to ask better, more informed questions.
  • Maintenance. A big difference with projects you might do on a semester in 6.101/6.102/etc and projects you do in SIPB or industry, is that you now need to care more about how the project does in the long-run. A SIPB project lasts for years or decades, and hence documentation is important to keep the project evolving as times change.
  • Enhance collaboration, encourage best practices, improve usability, save time, ... 

Overall, having a robust documentation system allows SIPB to be more productive in all forms imaginable, making it easier to provide quality services to the MIT community and furthering the Goals of SIPB.


Currently (as of Jan 2025), it is very far from straightforward to traverse through the SIPB knowledge. It's all spread around AFS, Github, the SIPB website, cluedumps.mit.edu, random websites – all of which is hard to keep track of and much is outdated. Hence, there is a need for a place to serve as a central source to organize all our endeavors.

And yes, Confluence is not perfect, but why should want something perfect anyways?

Confluence is readily available and already powerful. Otherwise, we would have to build and maintain our own documentation system, which can be very time consuming and cumbersome, specially if we really want it to make it look nice and customized. And after all that work, how much better would it be compared to Confluence? As they say, perfection is the enemy of progress, or something like that.

Instead, by immediately utilizing IS&T's Wiki service, we can focus on the most important thing – which is actually writing all the necessary documentations. 

Moreover, Confluence has gained widespread usage in industry. Hence, it can prove useful for students to get familiarized with the system and its quirks.

Though, this definitely doesn't mean we shouldn't consider other options. If you have strong arguments in favor of a different system, then we should discuss.

Edit

These are minimal guidelines to keep in mind while documenting all our SIPB 

  • No labels