Добрый день.
Являясь одним из разработчиков открытого проекта Embox, я часто слышал (в последнее время слишком часто) о том, что проект интересный, но поскольку документации нет, его невозможно использовать. Мы отвечали, что документация в каком-то виде есть, что мы всегда можем ответить на вопросы, что в крайнем случае можно попытаться разобраться самостоятельно, ведь проект открытый, но все это не подходило. Пришлось заниматься данной, очень неприятной для разработчиков, темой. Но естественно, статья не о том, что документацией заниматься “неприятно”! A о том, как мы сделали процесс разработки документации более комфортным. Ведь в любом более менее большом проекте, обязательно возникают вопросы, связанные с документацией.
Для тех, кому лень читать, сразу скажу, что в итоге мы пришли к разработке документации в формате markdown. Ну а тех, кому интересны детали, причины, почему именно markdown и какие есть плюсы и минусы у данного подхода, прошу под кат.
Являясь одним из разработчиков открытого проекта Embox, я часто слышал (в последнее время слишком часто) о том, что проект интересный, но поскольку документации нет, его невозможно использовать. Мы отвечали, что документация в каком-то виде есть, что мы всегда можем ответить на вопросы, что в крайнем случае можно попытаться разобраться самостоятельно, ведь проект открытый, но все это не подходило. Пришлось заниматься данной, очень неприятной для разработчиков, темой. Но естественно, статья не о том, что документацией заниматься “неприятно”! A о том, как мы сделали процесс разработки документации более комфортным. Ведь в любом более менее большом проекте, обязательно возникают вопросы, связанные с документацией.
Для тех, кому лень читать, сразу скажу, что в итоге мы пришли к разработке документации в формате markdown. Ну а тех, кому интересны детали, причины, почему именно markdown и какие есть плюсы и минусы у данного подхода, прошу под кат.