Рубрика «документация» - 5

С тех пор как я перешел к работе над крупными, комплексными проектами, я продолжаю утверждаться в том что есть два типа программистов – назовем их логики и визуалы.

  • Логики – это программисты с классическим флёром. Чтобы познакомиться с новой технологией они идут и читают документацию. Четкость кода – повышенная, ни шага влево, ни шага вправо. От забора и до обеда. Непритязательность к удобству работы с кодом пугает – кажется, что они могут работать и с минифицированным кодом, пользуясь одной только функцией поиска.
  • Визуалы – это люди, подходящие к коду более творчески, абстрактно. Чтобы изучить технологию они идут в youtube и смотрят видео про дельфинов уроки. В коде им важно разделение на осязаемые блоки, отсутствие простыней на 1000+ строк, возможность реализовать по-новому. Выполняя новую задачу они будут пристреливаться и искать свой вариант решения вместо поисков уже имеющегося на просторах интернета.

Речь в этой статье пойдет об инструменте разработки, без которого я, как представитель второго типа, уже не мыслю разработку проектов размером больше 250 строк и который, я уверен, будет полезен нашим коллегам из классического типа – он сделан в сотрудничестве с одним из вас – восходящей звездой мира программирования Степаном! Итак!
Читать полностью »

Как правило, каждый разработчик программного обеспечения хочет предоставить своим пользователям качественную документацию. И мы, компания Renga Software, не исключение.

В этой статье я, технический писатель Renga Software Анастасия Тян, расскажу, от чего мы отталкивались в начале разработки справки для BIM-системы Renga и к чему в итоге пришли.

Итак, пользователи наших продуктов ― архитекторы, проектировщики и конструкторы. Для них был разработан минималистичный интерфейс Renga, состоящий всего из нескольких панелей и рабочего пространства, ограниченного лишь размерами мониторов. Разумеется, хочется, чтобы документация не отставала от интерфейса в оформлении, а также предоставляла пользователям всю необходимую информацию.

Как мы делаем справку для Renga - 1

С самого начала разработки Renga было понятно, что нам необходима современная онлайн-справка. Также было принято решение, что мы не будем отказываться от оффлайн-справки в формате CHM, чтобы пользователи могли к ней обращаться без подключения к интернету и не тонуть в ворохе html-файлов.Читать полностью »

Привет! Предлагаю вашему вниманию свободный перевод статьи «Good code is its own best documentation» от Amit Shekhar.

image

Хороший код, как хорошая шутка — не требует объяснений.
Читать полностью »

В действительности все совершенно иначе, чем на самом деле.
Антуан де Сент-Экзюпери

Многое в разработке руководства пользователя регламентировано и описано ГОСТами. Но при создании больших гетерогенных систем могут возникать вопросы, не до конца освещенные этими документами.

Отношение к руководству пользователя бывает разным. Многие совсем не задаются вопросом, каковы место и роль документа в процессе разработки больших гетерогенных информационных систем, для других же все и так ясно. Не спешите. В статье мы рассмотрим подходы к организации процесса создания и поддержания в актуальном состоянии этого важного документа, оценим значимость руководства пользователя для всей информационной системы в целом и придем к некоторым неожиданным выводам.

Статья будет полезна для тестировщиков, технических писателей, аналитиков и даже для руководителей проектов.

Как с помощью руководства пользователя повысить качество информационной системы - 1Читать полностью »

ioninja

Под данным изречением-мемом, взятым с замечательной картинки Владимира Филонова, поставит свою подпись каждый человек, имеющий хотя бы отдалённое отношение к программированию. Весь вопрос, как? Как именно документировать-то?

Нижележащий текст преследует несколько целей:

  1. Дать краткий обзор (читай — немного погундеть на тему) неудовлетворительного состояния инструментария, применимого к хтоническим чудовищам мира C/C++;
  2. Предложить своё альтернативное решение (бесплатно-без-СМС-и-регистрации — проект некоммерческий и выложен на GitHub под MIT-лицензией);
  3. Призвать сообщество пообщаться на тему и собрать идеи;
  4. Пригласить присоединиться к разработке проекта на GitHub.

Сразу оговорюсь, что хотя проект создавался в первую очередь как альтернатива, а точнее, дополнение Doxygen для сишных и плюсовых API, архитектурно он в равной степени пригоден и для других языков. Это позволяет создавать порталы документации разноплановых библиотек — сами библиотеки могут быть написаны на разных языках, а в документации будет единство стиля во внешнем виде и поведении.

Читать полностью »

Мне хотелось бы думать, что я вполне прилично знаю Node. Вот уже три года, как ни один из сайтов, над которыми я работал, не обходится без него. Но документацию до сих пор я как следует не читал.

Мне нравится записывать полезные вещи об интерфейсах, свойствах, методах, функциях, типах данных, и обо всём прочем, что относится к веб-разработке. Так я заполняю пробелы в знаниях. Сейчас я занят документацией к Node.js, а до этого проработал материалы по HTML, DOM, по Web API, CSS, SVG и EcmaScript.

image


Чтение документации Node.js открыло мне немало замечательных вещей, о которых я раньше не знал. Ими я хочу поделиться в этом небольшом материале. Начну с самого интересного. Так же я обычно делаю, когда показываю новому знакомому свои гаджеты.
Читать полностью »

Два месяца труда одним URL: ru.vuejs.org
Кроме того, переведена документация Vuex: vuex.vuejs.org/ru
Ожидает merge'а деплоя документация vue-router, появится здесь: router.vuejs.org/ru

Огромное спасибо Konojoto и всем остальным, кто помогал переводить и вычитывать документацию (полный список контрибьюторов см. на github.com/translation-gang)

Читать полностью »

Linux ядро на сегодняшний день — самый динамичный, сложный, крупный проект с открытым кодом. Как же обстоят дела с его документацией? Существует прямая связь: чем качественнее и доступнее документация проекта, тем проще для посторонних изучить основы дела, освоиться и стать полноправным участником.

Документация Linux ядра переходит на Python Sphinx - 1

На семинаре Kernel Recipies мейнтейнер документации Linux ядра Jonathan Corbet рассказал о нынешнем положении дел с документацией и о том, как будет совершаться переход от анархии к порядку. Первые успехи в этом начинании уже есть. Некоторые документы были недавно конвертированы в ReStructuredText с помощью питоновского Сфинкса. О том как это было рассказано внутри.

Читать полностью »

Frontend: Разработка и поддержка - 1

Давайте представим, что вас перевели на новый проект. Или вы сменили работу и о проекте максимум только слышали. Вот вы садитесь за рабочее место, к вам приходит менеджер, жмёт руку и… прямо сходу открывает страницу проекта, тыкает пальцем в монитор и просит вставить «информер о предстоящем событии Х». На этом вы расстаётесь… Что делать? С чего начать? Как создать «информер»? Где найти нужный шаблон? И море других вопросов.

Под катом будет рассказ, как мы стараемся организовать эти процессы, какие инструменты создаём для препарирования SPA. Кроме этого, мы поговорим о технических подробностях реализации Live Coding / Hot Reload и чуток о VirtualDom и React с Angular.
Читать полностью »

Свершилось!

PostgreSQL приходит в Россию
Наша компания официально завершила перевод документации PostgreSQL текущей версии на русский язык и в этой публикации мы хотим поведать, как это было. Мы также хотели бы рассказать о пути, который мы прошли для достижения этой цели (и какие направления мы перепробовали), но это, пожалуй, тема для отдельной статьи.

Перевод самого PostgreSQL на русский язык начался в далёком 2001 году, тогда вышла только версия postgresql 7.1, и в самом postgresql усилиями в том числе и наших разработчиков только появлялась возможность локализации сообщений (см. babel.postgresql.org).
Впервые перевод сообщений на русский был включён в версию 7.2, вместе с переводами на французский, немецкий, шведский, китайский и чешский.
Читать полностью »


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js