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

Фоновая информация

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

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

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

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

Фактический вопрос

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

Что будет стоить развернуть вики, а не просто использовать то, что у нас уже есть?

Ответ 1

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

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

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

Для документации разработчика, wiki намного лучше, так как вы можете легко связывать документы, и даже если по той причине, что разработчики склонны ЛЮБИТЬ разметку wiki! Заставляет чувствовать, что они пишут код, а не документ. Ну, хорошо, мне это нравится. Документы Word? бесконечное разочарование, особенно для фрагментов кода и таких вещей, как API. Вики "обычно обрабатывают код и структурированное форматирование действительно, очень хорошо.

Но вот главное мое сообщение:

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

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

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

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

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

Хорошо работает.

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

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

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

* note: виртуальный HOST. Не виртуальная папка.

Ответ 2

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

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

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

Ответ 3

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

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

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

Ответ 4

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

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

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

Ответ 5

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

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

Ответ 6

Во-первых, просмотрите fooobar.com/questions/241020/.... Аналогичный вопрос был задан в отношении sharepoint wikis, и ответы там как pro, так и con действительно полезны и описывают часть вопроса "невозможно в Sharepoint".

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

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

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

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

Sharepoint Wiki

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

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

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

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

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

Ответ 7

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

Затем возникает вопрос, какая wiki

Почти любая wiki лучше, чем вики-страница SharePoint, что за пределами шутки

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

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

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

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

Ответ 8

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

Ответ 9

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

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

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

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

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

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

Ответ 10

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

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

Ответ 11

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