вот стайлгайды тоже хорошо работают, отличный совет

Писателям не придется смотреть несколько сайтов на чужую доку, а использовать только нужные вам правила

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

про стайлгайд мысль отличная!
но да, его надо сделать
тогда вопрос - есть ли примеры стайлгайдов? что туда входит?

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

стайлгайды на англйском можно поискать здесь в чате и просто нагуглить
Например, у Google или Microsoft.
Также у Google есть хороший и короткий курс для писателей. Его можно даже автоматически перевести на русский, смысл не потеряется

+ у нас нет редактора, редакторами выступают продакты (так как они заказчики)
работает сейчас плохо, потому что у всех желание просто переписать...

Вы можете описать там все проблемы, которые возникают у ваших писателей:
какие термины использовать
какие стандартные формулировки использовать
как единообразно описаывать объекты системы
требования к скриншотам.
Да хоть про использование буквы Ё

https://developers.google.com/style - вот у гугла

http://rdpk.ru/ - редполитики у разных медиа. Может и не сильно поможет, но для вдохновения подойдет

Привет!!

Вы выбрали классный подход!!

Вот есть самоучитель по Питону: https://letpy.com/python-guide/variables/

Я обожаю, как пишет этот автор.

Можно почитать и взять за пример.

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

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

А чем это не аналог уже существующего paligo? https://paligo.net/

+

И, кстати, в этом чатике я неоднократно слышал, что DocBook - фсе. Но не все так просто :) Как я и говорил, все перешло в стадию mature.
"Paligo's content model is based on DocBook, but a customized topic-based version of it. But even with the customization, it is close enough so you can in most cases refer to this reference for a list of the elements, and what they are used for: Element reference." (https://paligo.net/docs/en/the-basics-of-topic-editing.html)

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

Мы в Docma ориентируемся скорее на рынок средних и малых компаний, которые хотят минимизировать время, затраченное на оформление документации, не теряя при этом в ее качестве или актуальности. Важным для нас условием является низкий порог входа, чтобы проект документации могли наполнять все от разработчиков до контент-менеджеров. Совмещая популярность markdown и удобство wysiwig, мы хотим дать возможность сразу импортировать имеющуюся в команде markdown-документацию и начать работать с ней более удобным способом. Вторая важная для нас задача - интеграции в пайплайн разработки, например: верификация страниц, которые описывают те участки кода проекта, которые были изменены.

Docma должна быть удобна и для быстрого прототипирования идей, и для внутренней документации для команды, и для публикуемого контента. Хотим дать возможность всем в команде, от разработчиков до контент-менеджеров, с одинаковым удобством вносить правки.

Ну и с точки зрения денег, Paligo на тарифе с интеграциями в репозитории, стоит $269/чел/мес. Мы планируем быть намного доступнее.

Как говорится, вы хотите и пирожок съесть и честь не потерять. Очень, ОЧЕНЬ большие требования.

Хорошее описание. А в чём вы видите вашу ключевую ценность?

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

Но я - не вы, поэтому просто посмотрю, что выйдет.

Удобство. Это растяжимое понятие, ведь оно состоит из кучи связанных мелочей. Если говорить образно, то инструмент должен быть под рукой, но не стоять на пути.