На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- СкуммВМ
- Технический писатель:
- Кади
- Название проекта:
- Запустить портал документации
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
Цели:
- Создавать высококачественную документацию для конечных пользователей с указанием версий путем объединения больших объемов информации из разрозненных источников и переписывания информации для обеспечения ясности, последовательности и полноты.
- Документация должна быть простой для понимания новичками и не должна быть покровительственной для технически подкованных пользователей.
- Создать портал документации с помощью генератора статических сайтов.
- Готовить документацию для конечных пользователей, готовую к будущему, путем создания шаблонов и подробных инструкций для будущих участников открытого исходного кода.
Текущая ситуация:
- Доступная документация ScummVM разбросана по нескольким источникам.
- Информацию трудно найти, и она часто дублируется; на непонятных страницах легко заблудиться.
- Трудно понять, какая информация актуальна, а какая устарела.
- Некоторая информация отсутствует или является неполной.
Устранение проблемы:
Предлагаемая структура документации:
Целевая страница |-- Начало работы | -- Quick start guide |-- Installing ScummVM | |-- Nintendo 3DS | |-- AmigaOS | |-- Android | |-- (every) | |-- (common) | |-- (supported) |
-- (платформа) |-- Использование ScummVM | |-- Панель запуска | |-- Глобальные настройки | |-- Настройки игры | -- Keyboard shortcuts |-- Advanced options | |-- Cloud and LAN | |-- Control Mapping | |-- Configuration | |-- Command line options | |-- Graphics |
-- Музыка и звук |-- Помощь | |-- Часто задаваемые вопросы | |-- Контакты | |-- Известные проблемы | -- Reporting a bug |-- Game Notes
-- Примечания к выпуску
- Начиная:
Новые пользователи часто ищут краткое руководство, чтобы начать работу как можно быстрее. Хотя установка ScummVM может быть сложной на некоторых платформах, ее установка на компьютер — нет.
Краткое руководство должно охватывать следующее:
- Как установить ScummVM на Windows, Mac и Linux.
Как загрузить, добавить и запустить игру.
Установка ScummVM:
В тех случаях, когда установка не является интуитивно понятной или у пользователя нет сильной технической базы, ему необходимо подробное руководство по установке ScummVM на любую из поддерживаемых платформ.
На каждой подробной странице установки должно быть указано следующее:
- Любые системные требования/предварительные условия.
- Как скачать подходящую версию ScummVM.
- Как установить ScummVM.
- Как загружать игры на выбранную платформу, особенно если игра не предназначена для этой платформы.
Как запустить ScummVM, добавить игру и запустить игру.
Использование ScummVM:
Пользователям нужны справочные документы, объясняющие, как использовать ScummVM.
Справочные документы должны охватывать следующее:
- Интерфейс лаунчера; как выглядит каждое окно и вкладка, а также как они функционируют.
- Объяснение доступных настроек, как глобальных, так и специфичных для игры.
Сочетания клавиш/горячие клавиши.
Расширенные параметры:
Опытным пользователям нужна дополнительная, более техническая информация о доступных им опциях для настройки работы их игр.
- Примечания к игре:
Любая информация, специфичная для игры, которую должен знать пользователь; включая, помимо прочего: - Особенности установки - Любые необходимые дополнительные файлы - Необычные или другие элементы управления
- Известные проблемы:
Этот раздел должен содержать все известные ошибки, характерные для данного выпуска.
- Примечания к выпуску:
Хотя наша документация будет версионной, наличие раздела «Примечания к выпуску» может оказаться полезным для предоставления сводки изменений в последней версии. Сюда могут относиться некоторые области, которые в настоящее время выходят за рамки данной документации, например новые поддерживаемые игры или информация о новых движках.
План атаки:
Я предлагаю начать с создания шаблона для страниц установки ScummVM, так как для меня это будет самый простой способ получить необходимую информацию от сопровождающих/разработчиков портов (особенно там, где эта информация скудна или не существует). Я предварительно заполню любую имеющуюся у меня информацию из существующей документации, которую затем можно будет проверить на полноту, точность и актуальность или добавить по мере необходимости.
Далее я прочесаю существующую документацию; README, вики и веб-сайт. По ходу буду переписывать и дополнять каждый раздел по мере необходимости и перетягивать всю информацию в новый портал. Я также буду записывать, какая информация и откуда берется, чтобы гарантировать, что после запуска портала не возникнет двойных ошибок, противоречий или других аномалий.
На протяжении всего процесса я буду поддерживать связь с наставником(ами), разработчиками, сопровождающими портов и любыми другими экспертами в данной области, чтобы найти недостающую информацию, а также следить за тем, чтобы каждая страница была максимально актуальной и полной.
В духе сотрудничества и при условии одобрения наставника(ов) я хотел бы, чтобы портал незавершенной работы был доступен сообществу ScummVM на протяжении всего процесса написания, чтобы получать обратную связь в режиме реального времени и гарантировать, что ничего не пропущено. путь.
Я предлагаю использовать руководство по стилю, такое как руководство по стилю документации для разработчиков Google, чтобы обеспечить единообразие этой работы и всей дальнейшей документации.
По возможности я буду использовать скриншоты, картинки и другие наглядные пособия для улучшения понимания.
Предлагаемый график:
Сплочение сообщества 17 августа – 13 сентября 2020 г.
Продолжайте тратить время на общение с наставником(ами) и более широким сообществом ScummVM, чтобы уточнить видение проекта и доработать такие детали, как структура и содержание документа.
Неделя 1 14 сентября – 20 сентября
- Создайте шаблон для страниц установки для конкретной платформы.
- Предварительно заполните шаблоны любой существующей информацией и разошлите соответствующим сопровождающим/разработчикам портов для получения дополнительной информации.
2 неделя 21 сентября – 27 сентября
- Настройте новый портал документации.
Неделя 3 28 сентября – 4 октября
Использование ScummVM: - Интерфейс - Глобальные настройки Установка ScummVM: - Мне возвращаются руководства по установке для конкретных платформ в виде готовых шаблонов.
Неделя 4: 5 октября – 11 октября
Использование ScummVM: - Настройки игры - Сочетания клавиш. Установка ScummVM: - Мне возвращаются руководства по установке для конкретных платформ в виде готовых шаблонов.
Неделя 5 12 октября – 18 октября
Дополнительные параметры: - Облако и локальная сеть. - Сопоставление элементов управления. Установка ScummVM: - Мне возвращаются руководства по установке для конкретных платформ в виде готовых шаблонов.
6 неделя 19 октября – 25 октября
Расширенные параметры: - Конфигурация - Параметры командной строки. Установка ScummVM: - Мне возвращаются руководства по установке для конкретных платформ в виде завершенных шаблонов.
Неделя 7 26 октября – 1 ноября
Расширенные параметры: - Графика - Аудио Установка ScummVM: - Мне возвращаются руководства по установке для конкретных платформ в виде завершенных шаблонов.
Неделя 8 2 ноября – 8 ноября
Помощь: - Часто задаваемые вопросы - Контакты - Известные проблемы
Установка ScummVM: — Мне возвращаются руководства по установке для конкретной платформы в виде готовых шаблонов.
Неделя 9 9 ноября – 15 ноября
Помощь: - Сообщить об ошибке - Примечания к игре - Примечания к выпуску
Установка ScummVM: - Завершите работу над всеми руководствами по платформе, которые еще не завершены.
Неделя 10 16 ноября – 22 ноября
- Окончательное редактирование, корректура и доработка любых решений, связанных с порталом, таких как навигация по боковой панели, настройки темы/CSS и т. д.
- Убедитесь, что все ссылки работают должным образом.
- Проверьте правильность отображения изображений/гифок.
Неделя 11 23 ноября – 30 ноября
- Завершите все невыполненные задачи и официально запустите портал!
- После запуска портала удалите избыточную информацию из других источников по согласованию с наставником(ами).