Date: prev next · Thread: first prev next last
2016 Archives by date, by thread · List index


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

Context


Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License (MPLv2). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.