View Source

Goal

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.
A 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 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. 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.

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.

Maintaining updated docs: Doc Wizards

You are always encouraged to add or suggest changes on any page, and to use your creativity and discretion to improve the documentation to make it more engaging, informative, and relevant.

Moreover, as an initiative to do encourage active documentation and prevent outdated content:

We request that every relevant page should have a list of "Doc Wizards".
- Usually, write this list at the top or bottom of the page.
Anyone reading the document is encouraged to ask questions or request clarifications to the Wizards, via email/mattermost/in-person/etc.
If a page receives no updates over a long time (depending on the content, usually 0.5-1.5 years), then a notification should be sent to the Wizards requesting an update or a confirmation that no changes are needed.
You can always remove yourself as a Wizard, but if you do so, please ensure that there's at least one other wizard – and if not, find one or train one in the wizardry arts.

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.