Хотя эта идея на первый взгляд может показаться глупой, упрощенной и слишком общей, я хотел бы предложить стандартый способ документирования проектов с открытым исходным кодом. Я знаю, что каждый проект индивидуален и моя идея уже вызвала у вас улыбку, но я надеюсь вы поймёте меня, если прочитаете этот небольшой пост.
Мотивация
Нас, авторов кода, стандарт спасёт от необходимости придумывать структуру документации для очередного проекта. Намного проще заполнять пробелы в заранее подготовленной структуре, чем думать о ней каждый раз. А чем проще и быстрее это будет происходить — тем больше разработчиков будет создавать хорошую документацию. (В конце концов, у нас останется больше времени на код и архитектуру — прим. пер.)
Стандартный формат также может сделать документацию более простой для понимания, если читатель будет знаком с её структурой. Для большинства вещей дизайн является лучшим способом привлечь потребителя, и именно дизайн ему нужен. Так что желание удовлетворить всех часто приводит к тому, что никто не оказывается удовлетворён, это касается и документации. Несмотря на то, что для обучения стоит применять персональный подход, я считаю, что тщательно продуманная и организованная документация позволит охватить больший процент потенциальных пользователей. Попытка же удовлетворить желания всех приводит к чрезмерному документированию: подобную документацию трудно сопровождать и она отпугивает читателя.
Во всяком случае, это только первый черновик стандарта, который я предлагаю. Комментарии приветствуются!
Читать полностью »
