Да, и еще, можете попробовать посмотреть на какой-нибудь бундесбирже фрилансеров. Немчики хорошо делают дизайн - не знаю, почему. Наверное, у них развито направление Visual Art.
"Дело в том, что есть ощущение, цитата: "весь дизайн сделали сами - проще, быстрее, дешевле." — что так и выйдет. Только времени жалко на такую лабуду."
Дело в том, что это не лабуда. Если вы сделаете сами, то вы НЕ получите:
1. Головняка при взаимодействии со фрилансером.
2. Срывов сроков работ.
3. Неподконтрольный дизайн, который утечет еще хрен знает во сколько компаний.
Да, иногда приходится заниматься неподходящими делами, но это экономит столько нервов и времени, что иногда после завершения думается: "не зря все же взялись" :)
"Дизайн нужен, чтобы гайд выглядел нормально..." - это не ответ :) Ответ это - "чтобы продать подороже". "чтобы нас воспринимали, как крутых чуваков, способных замутить крутую документацию", и т.п.... ну, вы поняли :)
FYI: "Шрифты тоже не интересно, есть корпоративный стандарт" - кстати, это часть дизайна. Кроме того, учтите, что многие шрифты нельзя поставлять на внешний рынок, если они не куплены! Имейте в виду, что может возникнуть ситуация, когда дизайнер вам скажет - такие шрифты использовать не будем.
Что касается минимализма, что самый что ни на есть минимализм - у DAPS (гуглите: DAPS opensuse print manual в поисках по картинкам).
Насчет остального, то варианта два:
1. Вбить в гугле: user manual system requirements filetype:pdf и пройтись по десятку существующих. Вторая фраза нужна для того, чтобы отсечь все руководства по хардверным штукам. Там в смысле дизайна бывает иногда такая жесть, что ...
2. фрилансеров, как подсказывают ниже. Но, как показывает личная практика, все зависит от исполнителя. У нас было так, что в итоге весь дизайн сделали сами - проще, быстрее, дешевле.
Stas Karter: Вы лучше спросите, что вам непонятно :)
1. Что это за формат хорошо написано здесь: https://ru.wikipedia.org/wiki/DocBook либо на англоязычной версии.
2. Как делать из этого формата представление (т.е. выходные форматы) написано здесь: wiki.docbook.org
3. Где редактировать - да хоть в Notepad, vim и т.п. Если интересует GUI, то можно попробовать www.xmlmind.com/xmleditor НО! Он стоит денег, поэтому вам, как студенту, можно использовать evaluation только в течении 30 дней. Не думаю, что вы будете его покупать.
maximus: DITA вам не нужна, уж поверьте :)
Если вы определились с форматом (например, Markdown), тогда дальше уже ищите примеры отображения и смотрите, каким образом это устроено у каждой системы.
Почему так? Просто text-based форматы (adoc, md, rst) в это плане более требовательны к изначальной структуре - т.е. вы не сможете потом автоматически их разбивать на куски (про использованием sed/awk я не говорю). С xml-based форматами (Docbook, DITA) в этом смысле проще, т.к. всегда есть xslt, который разобьет вам все, как надо в любой пропорции.
Одна из ошибок начинающих - смотрят на интерфейс. НО! Интерфейс и формат хранения/редактирования - это две совершенно разные вещи. Вам надо сначала определить формат хранения, а потом уже под этот формат хранения искать себе морду для генерации. Только так.
Виталий Столяров: Тогда вам надо:
1. Определить, что конкретно вы будете документировать.
2. Надо ли вам выцеплять это автоматически.
3. Попробовать несколько инструментов в виде теста. Про doxygen вы уже знаете. Можете еще попробовать Sphinx. Или еще погуглить. Для REST - я приводил инструменты ранее.
Виталий Столяров: Вы противоречите сами себе. Приведу цитаты:
- "сопровождение написанного кода документацией, автоматически сгенерированной из комментариев к соответствующему коду"
однако с другой стороны вы отвечаете на вопрос:
- "Надо ли хранить версионность всего этого добра - нет".
Сопровождение НЕ может быть без SCM. Это принципиально.
Давайте я объясню вам, в чем вы неправы. Вы хотите получить "что-то" и "прямо сейчас", "не задумываясь о требованиях". Я же, со своей стороны, даю советы "как надо", а не "как хочется". Безусловно, на тостере много людей, которые практически всегда отвечают не задумывась "Я использую X, попробуй", "Слышал, что Y подходит". Если вас удовлетворят такие ответы без уточняющих вопросов - без проблем - думаю вам здесь подскажут.
Виталий Столяров: Так в том то и дело. По требованиям выбираются инструменты и процессы, а не наоборот. Вы, конечно, можете попробовать от обратного, но это будет, мягко скажем, неоптимально :)
Виталий Столяров: Виталий, по вашему ответу я уверен, вам надо основательно подумать над моими изначальными вопросами, осознать их и ответить на них. Даже, если это займет несколько дней. На текущий момент я вижу - вы смешиваете все в кучу. Т.е. вы просите подсказать вам решение конкретной проблемы, но не можете сформулировать четко эту проблему(-ы) - например, у вам по ходу диалога появляются все новые и новые требования.
Виталий Столяров: Так вы сначала определитесь, нужен только API или нет? :) Т.к. разница очень большая. Если вам нужен только API, то вам будет достаточно:
- генератора комментариев из кода.
- что-то типа Swagger (для REST API). Здесь еще существуют другие нотации и инструментарий - RAML и WADL (последний основан на xml, первые два на json + yaml в качестве "человекочитаемого" варианта).
- web сервер для отображения всего добра.
- скрипты генерации (проще самописные, т.к. вариантивность маленькая).
ОДНАКО, если вам надо делать нормальную документацию: ТЗ, архитектурные документы, руководства администратора, white papers и т.п. (т.е. то, что создается человеком, как документ, содержит иллюстрации и т.п.), то инструментарием выше вам не обойтись.
Вам придется добавлять:
- SCM (обязательно)
- Authoring tools (чтобы писать)
- generation tools + CI (чтобы все генерилось без участия человека).
Если вероятность расширения продукта велика и вынос наружу будет (а это только вам решать), то следующие элементы в структуре must have:
- SCM
- Authoring tools
- CI
Лично я занимаюсь сложными системами, и, конечно, мог бы вам посоветовать использовать много чего, но все-таки вопросы цены внедрения/сопровождения имеет немаловажное значение. Не зря я вам посоветовал посмотреть Где лучше всего вести документацию по сервису? - это напрямую относится к деньгам при выборе решения.
Виталий Столяров: И еще... как я понимаю, нужен только API и все? Т.е. никаких руководств, архитектурных решений и т.п. (т.е. "нормальных документов") не нужно.
Виталий Столяров: п.2 противоречит п. 1, а также пункту "для чего". Печатка нужна только для распространения наружу. Вы не будете печатать у себя + искать внутри. Вам нужен только html c поддержкой поиска.
п.7 - вы уверены в том, что вам не нужно будет держать версионность? Т.е. вопрос коллеги типа "а как там у нас это было реализовано в предыдущей останется без ответа" (точнее, без ответа из документации).
На уровне XSLT вопрос не в количестве добавляемых объектов (хоть 5, хоть 1000), а в сложности логики добавляемых элементов. Написать обычное xslt преобразование, добавляющее внутрь всех элементов А элемент B - дело 5 минут. Другое дело, что кто возьмется за такое.
digiben: У вас две несовместимые вещи по требованию надежности: _старый_ системник и svn (т.е. src). Думаю, что VPS + backup на старый системник (или другой компьютер) будет лучше. Тем более, что VPS можно найти и за 200 рублей в месяц (ну, естественно, c использованием только по IP без NS).
Вся суть в том, что вам надо совсем отстранить "студентка-техписательницу" от какой-либо структуры и здесь это можно сделать. Т.е. вы даете ей редактор (в моей схеме - Authoring tool) и она там пишет - все. Остальное - цепочки преобразований, топиков и т.п. остается на уровне автоматизации. Здесь только один вопрос - сможет ли она владеть чем-то "не ворд" для набивания текста. По моему опыту - научить реально, хотя и с усилиями.
Вы можете попробовать (просто сделать один шаг) - загрузить www.xmlmind.com/xmleditor evaliation. Посмотреть сюда, как это работает: www.xmlmind.com/xmleditor/tutorial.html Хотя сразу же предупреждаю, что там по умолчанию все основано на gui-действиях и оно дольше, чем сделать keyboard shortcuts.
Вам надо понять только одну вещь - wiki и другие WISYWIG системы хороши для создания контента сотрудниками с нулевым уровнем знаний :) ... но ровно до тех пор, пока контентом не надо управлять. Когда начинается серьезная работа, то без single sourcing уже не обойтись.
www.indoition.com/previews/book-designing-en-previ...