Документация для разработчиков: Sharepoint Document Management против ScrewTurn Wiki

Справочная информация

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

Мне это показалось идеальной работой для вики, и, поскольку наша компания имеет возможность размещать только приложения ASP.NET, я приступил к исследованию доступных вики-сайтов ASP.NET. ScrewTurn Wiki показался мне наиболее подходящим, он очень полнофункциональный, и есть несколько доступных плагинов, которые были бы полезны в моей ситуации, включая подсветку синтаксиса и интеграцию с AD.

Однако, начав процесс развертывания ScrewTurn в нашей интрасети, внезапно вспомнилось, что, эй, у Sharepoint 2007 есть вики, и, поскольку у нас уже настроена Sharepoint, не могли бы мы просто использовать ее? Я провел небольшую оценку «вики» Sharepoint (в кавычках, потому что она почти не соответствует требованиям) и смог продемонстрировать, что она не подходит из-за множества недостатков, которые я не буду здесь перечислять.

На этом этапе было высказано предположение, что, возможно, мне вообще не нужна вики, не могли бы мы просто делать все в документах Word и вместо этого использовать функции управления документами Sharepoint?

Актуальный вопрос

Так что я ищу дополнительные боеприпасы, желательно от людей с опытом. Каковы примеры того, что будет сложно или невозможно с Sharepoint в контексте внутренней документации для разработчиков? В чем вики лучше? Эй, я непредубежден, в чем Sharepoint лучше?

Почему стоит развернуть вики вместо того, чтобы просто использовать то, что у нас уже есть?

Ответов (11)

Решение

Я надеюсь, что это будет полезно - дополнительные баллы или нет :)

SharePoint Server (SPS) или Windows SharePoint Services (WSS) ОЧЕНЬ хороши, если вы работаете с офисными документами - вы можете редактировать, регистрировать / выгружать, делиться, искать и т. Д. Я не думаю, что на рынке есть что-то, что подходит для эта функция (она также очень хорошо выполняет настраиваемые списки и прочее).

Но, как вы отметили, функция WIKI не соответствует стандартам.

Что касается документации для разработчиков, то вики намного лучше, так как вы можете легко связывать документы, и даже если по той единственной причине, что разработчикам нравится Вики-разметка! Создается впечатление, что они пишут код, а не документ. Ну ладно, мне это нравится. Документы Word? бесконечное разочарование, особенно в отношении фрагментов кода и таких вещей, как API. Вики обычно очень хорошо обрабатывают код и структурированное форматирование.

Но вот суть моего поста:

Если вы можете разместить ASP.NET - а если у вас есть SPS, вы уже можете это сделать! - тогда просто установите ОБЕИХ. Создайте новый виртуальный хост IIS, поместите в него STW (потому что SPS будет на собственном виртуальном хосте) *. Немного помассируйте DNS (чтобы вы могли ударить http://wiki или что-то в этом роде) и просто сделайте это.

Поскольку все это внутри вашей компании, а STW имеет безопасность и версии для Windows, безопасность не является большой проблемой. На каждую страницу можно ссылаться откуда угодно - в конце концов, это HTML-страница - так что вы можете ссылаться на нее из вики SPS, если действительно хотите. Я предполагаю, что есть некоторая блокировка, но не очень.

Здесь, в BBC Worldwide, мы используем ряд технологий:

  • Atlassian Confluence (WIKI) для некоторых проектов. Мне нравится эта вики, но это большая корпоративная система.
  • Винтовой поворот для некоторых вещей внутри отдела.
  • Trac для некоторых других вещей (кто-то еще установил его с SVN в нашем исходном репозитории, поэтому он немного используется - это приятно, мне это скорее нравится, но его легко настроить)
  • SPS / WSS для управления документацией.

существуют связи между STW, Trac и SPS - например, мы стараемся не хранить документы в виде вложений в trac, а делать ссылки на них в SPS и т. д.

Работает хорошо.

Что касается боеприпасов: SPS работает хорошо, если подходит для того, что вы хотите делать (или ВЫ можете соответствовать тому, что делает ИТ). Если нет, то вы либо облажались, либо вам нужно много заниматься разработкой, что на самом деле одно и то же :)

Но, если не считать того, что руководство очень смешно по этому поводу, я не вижу проблем с установкой обоих. STW в конце концов бесплатен. У вас есть сервер (ы).

И он получает документы, написанные разработчиками, что редко бывает плохо. Хорошо, если это должны читать настоящие люди, это плохо, но документы для других разработчиков? Все хорошо.

* примечание: виртуальный ХОЗЯИН. Не виртуальный СПРАВОЧНИК.

Сначала ознакомьтесь с этой веткой StackOverflow . Аналогичный вопрос был задан о вики-сайтах Sharepoint, и ответы на них, как «за», так и «против», действительно полезны и описывают часть вашего вопроса «невозможно в Sharepoint».

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

Библиотеки документов Sharepoint

Мой опыт показывает, что Sharepoint для документов - это неплохо. Это может быть нестабильным, и вы иногда потеряете правки или будете иметь проблемы с производительностью, хотя хорошая команда поддержки Sharepoint может помочь с некоторыми из них. Я нашел, что библиотеки документов Sharepoint лучше, чем хранение вещей в сети. Это упрощает создание ссылок на документы и библиотеки. Разумное использование свойств метаданных может сделать представление списка Sharepoint очень полезным для того, чтобы увидеть, что представляет собой документ, для чего он нужен и в каком статусе он находится, поэтому наши аналитики, менеджеры по менеджменту, разработчики и т. Д. Сразу узнают, кто имеет мяч и когда их что-то ждет. Это было начато для проекта пару лет назад; сегодня рабочие процессы Sharepoint 2007, вероятно, могут предоставлять уведомления.

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

Вики-сайт Sharepoint

Согласно ответу Криса Хайнса, трение - хорошее слово для описания проблемы. Для быстрого ознакомления с деталями внутренней инфраструктуры команды, похоже, нам больше подходит вики. Вики делает данные почти мгновенно видимыми, без необходимости сначала щелкать ссылку и ждать загрузки Word. Редактировать также быстрее и проще ... и хотя я все еще экспериментирую с этим, вики-страницы Sharepoint имеют контроль версий и позволяют «извлекать» статьи из вики.

Как вы и другие участники SO-потока отметили, по сравнению с другими вики-движками Sharepoint легковесен. В чем он лучше? Ну, я использую его, потому что он есть, не требует специальной настройки, лучше, чем ничего, и, честно говоря, он отлично работает для внутренних вещей, которые не должны быть надежными или ориентированными на клиентов. Его легко продать боссу, потому что это не стоит больше, чем мы уже потратили. Вики также не так легко скомпрометировать незакрепленные типы пушек, о которых я упоминал ранее, и мы сможем просмотреть контрольный журнал или выполнить откат, если это необходимо.

Добавлять и перекрестно связывать записи легко, хотя, если вы хотите встроить графику, вы должны сначала загрузить их в библиотеку Sharepoint. Вы также можете редактировать HTML в вики, хотя я не уверен, какие есть ограничения, и управление CSS, я считаю, недоступно без доступа безопасности и Sharepoint Designer. Так что все, кроме текста (например, таблиц), не очень надежно.

Пока мне это нравится больше, чем хранить все в виде документов. Незамедлительность просмотра и редактирования данных дает вики реальное преимущество. Это, безусловно, проще, чем вытащить документ и вернуть его обратно. Среднестатистическому разработчику, не склонному к документации, это помогает устранить препятствия, мешающие обновлению информации.

Есть еще кое-что, что нужно учесть. Ожидаете ли вы от ваших разработчиков энтузиазма и активного участия в редактировании вики? В таком случае вам могут понадобиться возможности обсуждения на другом движке вики. Мои разработчики похожи на большинство; две вещи, которые они ненавидят больше всего, - это тестирование и документация. Итак, я тот парень, который создает статьи, объясняющие процедуру сборки, использование среды базы данных, экземпляры приложений, карту серверов, контрольный список документации SOX и т. Д. Другие разработчики будут в основном ссылаться на нее и публиковать незначительные обновления. Наша поддержка версий и параллелизма не подвергается особой нагрузке.

Я сделал и то, и другое. После этого опыта вот мое предложение:

  • Если вам нужен WYSIWYG, и вас не волнует раздувание Sharepoint и отсутствие функций (вики упрощена, но содержит основные функции, которые вам нужны в вики), сделайте это. Он работает как вики и помогает, когда деловым людям нужно зайти в вики - гораздо меньше времени на обучение их использованию и т. Д.
  • Если вы умеете работать с barebone-системами и вам просто нужна простая вики, быстрая и гибкая, вам не победить.

Что касается того, зачем использовать вики, будь то завертка или sharepoint, - она ​​лучше Word docs в Sharepoint безоговорочно. Чтобы использовать Sharepoint, сначала вы должны загрузить документ, отредактировать, загрузить или использовать интеграцию с Office, что в лучшем случае является случайным. Wiki устраняет все препятствия и упрощает обновление. Устранение трений является ключевым моментом, потому что, когда вам приходится работать с текстовыми документами, вы просто не обновляете их так часто, как следовало бы. В вики это 2-секундная транзакция открытия / редактирования / сохранения. С помощью документа Word требуется несколько минут, чтобы загрузить слово, открыть документ, отредактировать, позаботиться о форматировании, сохранении и т. Д.

Вот расширенная вики с открытым исходным кодом для SharePoint, которая может быть более подходящей:

http://www.codeplex.com/CKS/Wiki/View.aspx?title=Enhanced%20Wiki%20Edition&referringTitle=Home

Я использую Sharepoint довольно регулярно, и мне это кажется медленным и раздражающим. Если все уже является документом Office, И если ваша компания желает поддерживать все компьютеры в рабочем состоянии с помощью версий Office, тогда Sharepoint может работать нормально. Если у вас есть множество версий Office (например, у нас), то это гораздо хуже. На моем компьютере установлены старые версии офисных компонентов, и интеграция не всегда работает правильно. Я научился вообще не пытаться использовать интеграцию.

Самое главное в любом решении - убедиться, что ваши люди знают, как его использовать. На раннем этапе у нас были некоторые проблемы (версии файлов с разными именами вместо использования встроенного в sharepoint управления версиями), которые на самом деле были просто пробелами в обучении людей.

В общем, для технических документов слово ужасное. Поскольку он очень плохо работает с большими структурированными документами, он способствует увеличению количества небольших документов без перекрестных ссылок между документами. Увеличьте это до любого значительного размера, и у вас возникнут проблемы с поиском документов, относящихся к проблеме, которую вы пытаетесь исследовать. Со временем вы обнаружите, что люди тратят все больше и больше времени на поиски информации, которая может быть записана, а может и не записана, через нагромождение текстовых документов, электронных таблиц, диаграмм Visio и даже презентаций в PowerPoint.

Помещение их в sharepoint просто заставляет вас направлять поиск через браузер.

Любой инструмент технической документации должен поддерживать перекрестные ссылки между документами, чтобы избежать потери этих ссылок. Вики достигают этого гораздо лучше, чем когда-либо. Кроме того, гораздо проще встроить сгенерированный контент, такой как словари данных или документы API, в вики, и вы можете сделать цели XRef стабильными.

Вики-сайт будет использоваться с гораздо большей вероятностью, чем набор словарных документов, просто потому, что быстрее и проще найти запись для редактирования или создания новой страницы, чем когда-либо будет куча текстовых документов!

Тогда возникает вопрос, какая вики

Практически любая вики лучше, чем вики SharePoint, это уже не шутка

Screwturn отлично, имеет ACL и WYSIWYG в v3, и его очень легко расширить

например, использование подключаемого модуля XSLT отлично подходит для встраивания вывода серверных процессов, сборок CI, тестов, статистики системы управления версиями и т. д.

Например, у нас есть плагин OLEDB, который считывает критические значения из различных баз данных компании и встраивает их в страницы, описывающие, что это за данные и какие значения они должны иметь. У нас есть одна главная страница, на которой перечислены все страницы с данными за пределами установленных диапазонов. Что-то вроде смеси FIT и инструмента системного мониторинга

Если у вас есть возможность управления тем, что «все» должно быть в SharePoint, то есть плагины Screwturn, которые отображают страницы Screwturn в формате PDF, HTML, xml и т. Д. (Затем вы можете преобразовать их в docx) и иметь сценарий для сброса измененного винта. страницы каждую ночь в SharePoint для поиска и "управления"

В настоящее время мы используем сочетание того и другого: sharepoint для спецификаций и формализованной документации и Wiki для «неявных знаний». У каждого из наших решений есть страница в вики, и это работает очень хорошо из-за простоты добавления контента.

Возможно, вы захотите проверить Confluence , поскольку это, вероятно, ведущая корпоративная вики-страница на рынке. Для этой вики также есть коннектор SharePoint . Как один из разработчиков коннектора SharePoint, я немного предвзят, но вы, вероятно, окажете себе медвежью услугу, если не ознакомитесь с некоторыми из имеющихся вариантов. Вики-сайты могут быть мощными и заразительными, но этого не произойдет, если вики-страницы не соответствуют требованиям.

Привет, у меня здесь есть опыт. Мы начали использовать ScrewTurn на работе, но нас попросили перейти на него, поскольку компания уже купила SharePoint. Качество документации снизилось, потому что документы Word не подходят для вики, и, как отмечали другие, SharePoint не на должном уровне.

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

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

Никто никогда не сможет быть доволен вики-страницей SharePoint, сравнивая ее с любой другой вики-системой.

Так что не сравнивайте это. Он имеет основные функции, необходимые для того, чтобы вики была полезной: вы можете вводить (в некоторой степени) богато форматированный текст вместе со ссылками на другие страницы, независимо от того, существуют они или нет. Щелкнув ссылку на несуществующую страницу, вы перейдете на страницу редактирования новой пустой страницы, что позволит вам сохранить страницу.

Да, поддержка изображений - отстой. Сначала вы должны создать изображение, а затем вставить URL-адрес изображения. Итак, потратьте две минуты и создайте библиотеку изображений для публикации вики-изображений.

Помните основные цели вики - не соревноваться с другими инструментами вики, а записывать идеи быстро и без остановки для их структурирования. Структура может быть добавлена ​​позже, если вообще будет.

Как уже говорили другие, telerik предлагает замену редактору Rich Text, есть проект CodePlex, работающий (медленно) над улучшениями, и, люди, это SharePoint - если вам это не нравится, вы можете настроить его. Это ASP.NET, веб-службы и Windows Workflow Foundation.

Я не рекомендую никому идти и покупать лицензию MOSS только для того, чтобы реализовать вики (или блог, если на то пошло). Но если у вас уже есть инфраструктура SharePoint (возможно, как часть Visual Studio Team System Team Foundation Server), сделайте это. Я видел несколько вики-библиотек SharePoint, используемых для значительного увеличения количества и качества документации для разработчиков, доступной нескольким группам в крупной организации по разработке программного обеспечения. Как только мы прекратили обсуждение того, насколько хороши были другие вики, довольно много документации появилось само по себе, как и предполагалось.