View Source

Goal

Why document at all? The reasons are almost endless, from ensuring that knowledge is shared and preserved, to reducing dependence on individual contributors and enabling long-term project sustainability.

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.
A Central Source of Truth. Ensures everyone has a clear understanding of the projects goals, design, and implementations.
Learning and Onboarding. There's less wasted time having to explaining everything from scratch, and – more importantly – new members gain important context that enables them to ask better, more informed questions.
Support Maintenance, 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, specially in the long-run.

Currently (as of Jan 2025), it is 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 we 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 documentation.

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 arguments in favor of a different system, then we should discuss.

Writing good docs

The following are some tips to keep in mind while documenting all our SIPB shenanigans.

Write it as if a freshman is reading it. Something that might seem obvious to you, might not to someone else. Don't assume too much knowledge from the reader, instead add clarifications and outside sources / further readings when using particular terms. If some concept or idea is very prevalent, consider making a cluedump article about it
Be concise and structured. For example, instead of rambling through many paragraphs, consider dividing it into sections, and maybe using lists, tables, or diagrams to make it more organized.
Include "metadocs". In other words, describe other docs you suggest the reader to further look at. This make it much easier to navigate through the web of docs.
Be you. There's no need to sound mechanical. Adding hints of your personality makes the writing more fun and engaging :)
Request feedback. Ask other project members for their perspective, to make sure everything is written clearly, and if they have other recommendations or would like to add their contributions.

Dealing with existing or external docs

As is with much of the content of the docs you might write, use your own discretion and intuition. Maybe it makes sense to migrate all the documentation to here, or maybe have links pointing to the previous documentation. Its up to you and the project team.