42

Writing great documentation

Добрался таки до статьи Writing great documentation (http://jacobian.org/writing/great-documentation/). Многие вещи были уже знакомы - но было и несколько интересных мыслей. Во первых немного смутило положение, что автоматически генерируемая документация javadoc не является документацией вообще - вместо нее надо писать честный документ руками. Соглашусь с автором наполовину. Краткое описание класса и описание методов не дают представление о том, как использовать весь модуль или библиотеку. Зачастую, чтобы это исправить в описании пакета или их набора дается несколько примеров с объяснениями концепций. С другой стороны - иногда в описании класса (class Calendar) содержится настоящий документ с примерами, пояснениями принципов работы, ссылками на дополнительные документы. 

Еще один момент, замеченный в статье. При перепроверке собственных документов - когда автор становиться редактором - довольно тяжело вчитываться и находить ошибки. Зачастую, исправлять собственный текст легче после определенного времени, когда начинаешь забывать, что дословно писал. Но есть и обходной вариант. Согласно статье, можно поменять внешний вид документа (шрифты, поля). Такая уловка позволит выключить память и включить внутреннего критика.

Что тестируем?

Соцопрос показал, что самым популярным памятником на земле являеться Статуя Свободы. Опрос проводился среди жителей Нью-Йорка. К чему это я? … в экзамене на знание английского - IELTS есть подраздел Listening. В нем экзаменуемому предлагаеться вписать в пробелы нужные слова по смыслу из прокручиваемой аудиозаписи. Но вся загвоздка в том, что вписывать слова (а значит и перечитывать куски текста) необходимо в процессе прослушивания. То есть здесь тестируеться не столько знание языка, сколько способность к паралельному выполнению нескольких дел. Говорят женщины с этим справляються лучше … и с тестом наверное тоже.

О сайтах IT аутсорсеров

Так и не досказал про Stella Systems…  в поисках R&D related вещей я забрел на их сайт в поисках информации по проектам и тех крутых штуках - которые они делают и уже сделали. Но меня ждало боооольшое разочарование. Сайт (как по мне - человеку не очень искушенному) приятен и красив во всех отношениях … дизайнеры и верстальщики потрудились на славу. На заглавной странице много молодых и веселых лиц сотрудников … а не на заглавных … хм а ведь они отсутствуют, как и любая инфа о компании. Я больше нашел про эту контору в developers.org.ua, где в частности написано, что они открытые и честные - как то не очень верится. Сайт представляет собой рекрутинговый инструмент - для набора вчерашних студентов, которым информация о компании не так и важна, главное, что они берут на первую работу. Я знаю несколько человек из этой компании, они умны и технически продвинуты … но после сайта у меня сложилось впечатление, что компания набирает сотрудников точно так же и таких же как в макдональдс …. Вильна каса!

R&D и местное IT

Услыхал я давеча, что есть в компании Stella Systems подразделение под загадочным для русского человека названием Research & Development. Название сие завораживает своей многозначностью и таинственностью. Из за такой многозначности некоторые IT конторы для красного словца в собственном описании имеют буквы R&D. Есть этому нерусскому слову очень даже русский перевод, который почти полностью отображает его сущность. R&D это то же самое что и НИИ. Цель научно исследовательских отделов не столько создавать что то новое и работоспособное - сколько публиковаться в научных изданиях и с этого нового делать патенты, чтобы на их основе можно было зарабатывать деньги. А где научная деятельность - там и научные степени. Но как то я не замечал в требованиях к кандидатам на должности хоть каких то упоминаний на опыт научных исследований. Так что если вы в описании местной фирмы встретите аббревиатуру R&D - смело стирайте первые две буквы, а потом задумайтесь об уровне профессионализма в такой организации.

Презентации на Sun Tech Days 2010

На (Sun) Tech Days 2010 было множество презентаций разных интересностей. Докладчики были в основном людьми видными и наверное уже собаку сьели на докладах и презентациях продуктов. Тем не менее было несколько ляпов, которые наблюдались у многих матерых парней:

1. Во первых это отсутствие нумерации страниц - без этого вопросы задавать довольно проблематично.
2. Далее - это отсутствие на первом слайде имени докладчика. Можно предположить что либо не они презентации делали - либо корпортативные правила это запрещают - в общем непонятно.
3. Многие выделяли ключевые понятия другим цветом, а не жирным шрифтом, и от этого было сложно прочитать и понять, что именно на этих, слегка позеленевших словах, докладчик пытаеться сделать ударение.
4. Презентации были сделаны с применением фирменного шаблона оракла, но так как видимо шаблон докладчикам отдали в последний момент - то в некоторых случаях слова наезжали на красные рамки и становились нечитабельными.

Еще было замечательное слово “hopefully” - которе я слышал несколько раз в процессе доклада при попытке откомпилировать и запустить демки. В большинстве случаев все отрабатывало нормально - но впечатление немного портилось.