Documenting how to develop with & for LibreOffice - a fresh approach?

[Olivier Hallot]

Hello Bjoern, Thorsten, All

Em 23/07/2016 22:48, Bjoern Michaelsen escreveu:
> Hi,
> 
> On Sun, Jul 24, 2016 at 01:50:20AM +0200, Thorsten Behrens wrote:
>> It seems interesting in a number of aspects; perhaps here's a way to
>> raise the profile & quality of our own programmability documentation
>> (by going there, or by cherry-picking good ideas)?
> 
> Hmm, I dont see much difference here between "stack exchange" and "stack
> exchange documentation". What exactly makes the difference there? Because I
> dont seem much (yet?).

I saw it as a way to create a TOC that links to entries that contains
carefully cratfted "questions" with precise and rich answers, using the
S.O. engine.

> 
> Also what is the difference between SE and ask.libreoffice.org from a
> feature perspective? For example, askubuntu.com is running on the SE stack, not
> on askbot -- but TBH I dont see much difference featurewise. I assume its
> mostly done for visibility.

I'm no expert but I see 2 softwares for the same purpose: create a
knowledge base feeded by the community of users, with the expectation
that answers to any question in the universe will show up filtering
massive Q's and A's. Reality shows not so easy.

Stack Overflow and Askbot are not a panacea but the bottom line is very
positive anyway. I moderate brazilian askbot and it works. But the
quality of either questions and answers are rarely acceptable as a
reference on the topic. People never search for topic before asking,
thus lots of repetition. People also don't use the voting system or even
bother do downvote bad answers (can spark emotions if you do). Maybe
this is community-related, but it is a fact.

Therefore, as I said above, carefull questions and rich & precise
answers equals workload anyway.

> 
> In general, I _love_ the idea to move our documentation focus to dynamic content
> on a platform that is easy to contribute to -- be that SE or askbot. That is
> _way_ more relevant and a much better fit to our development model than aiming
> for dead tree editions of documentation.

and wiki too. But like software development, we accept "patches" on our
doc only after peer review. Believe me, there is no better rich editor
than Writer and with a good DMS, unbeatable.

> 
> The thing that askbot/SE misses vs. classical documentation is that a structure
> beyond one topic and a way to focus and highlight a set of well-maintained
> content. A possible approach to this would be to have an index of highly
> relevant and well maintained content (this index could be in e.g. in the TDF
> wiki linking to various askbot/SE topics). The problem with askbot/SE/wikis is
> not the so much providing good content, it is making this content discoverable
> (dead tree documentation is even worse at this, though) and not sink in
> outdated and irrelevant content.

right, but mixing different tools is a maintenance nightmare.
Nevertheless, discoverability of the documentation/information is one of
my concerns at them moment.

> 
> So -- a draft proposal: Lets have an index of highly relevance topics somewhere
> (e.g. on the Wiki) and link the content by topic/chapter to well maintained and
> edited pages on askbot/SE whatever.

It can even be the Local Help, one F1 strike far. But see below.

> 
> @Olivier: Unless there are better proposal on how to work on this, could take
> up this rough idea and with the help of others grind a diamond out of it?
> Thorsten is right, we should any inspiration we can from SE. But even more
> importantly we should focus on getting dynamic content up in shape, it is _way_
> more important than printable, static dead documentation.

Today we have this documentation format scenario:

- Localhelp,  that contains a reference and a user guide, localized with
pootle, downloadable. Online version at help.libreoffice.org, XML files.

- LO Guides Books, produced in odt format, localizable with CAT by the
communities. Rich content, ease of edition.

- Askbot: on-line, user driven knowledge base, not localized, per language.

- TDF wiki: Some communities produce Q&A's and localized doc here.

- external, amateur blogs on LO topics, hints, tips&tricks (I'd like to
PLANETIZE this)

- other, found by googling around.

My take is that there is no one-size-fits-all, very hard not to
duplicate workload.

Books/chapters/sections are important for the training/migration
industry, and is the fastest way to port the documentation to other
languages. With a DMS (Document Management System) holding odf files and
good documentation project it can be the source for other formats.

Finally, on a totally different view, and addressing Thorsten concern on
software development documentation, opening a specific askbot instance
for developers looks very interesting to turn sterile doxygen
documentation into something readable for the rookie developer.

regards
-- 
Olivier Hallot
Comunidade LibreOffice
Rio de Janeiro - Brazil - Local time: UTC-03
http://ask.libreoffice.org/pt-br