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 explaining every time from scratch how something, 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.
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
Everyone is always encouraged to add or suggest changes on any page, and to use your creativity and discretion to improve the documentation, and making 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.