[FM Discuss] When to use FLOSS Manuals and when it's not the best tool / platform? your opinions

[Maren Hachmann]

Hi Mick,

I'm still following this list, even though I have switched to using
sphinx/readthedocs some time ago, and I'm happy to help you, and to help
the users to make a good decision.

Strengths of Booktype:

* easy to use for people who are not accustomed to write html or any
markup language, and cannot or don't want to invest time into learning
it, but get working on the content
* built-in community platform to facilitate exchange between editors
* a large community around it and people who 'randomly' come and ask if
they can help (for Flossmanuals)

Strengths of RTD/Sphinx:

* less fragmentation between the communication channels of a project
* full control over layout (you have that, too, if you're an admin of a
booktype instance, but not as a Flossmanuals user)
* semantic markup (i.e. the markup that is used does not only have a
style, but also an inherent meaning, like keyboard shortcuts, glossary
entries, code snippets, menu entries etc.)
* version control that allows you to not just view previous states, but
also combine them and going back to them, deciding what you want to keep
and what not
* plaintext files that are accessible as a whole, so things like search
and replace over a larger corpus will work
* a rudimentary system to enable translations (it doesn't use po files,
as far as I know, but it will keep translations together with the rest
as a single project, and they can be made available as translations to
select from

If I had to describe use cases, I would say that flossmanuals is better
for shorter prose-like manuals which are written by people of varying
technical skill level, and who do not have time or energy to invest into
preparations. It can be useful to get unexpected help from writers who
need experience for their CV or for study-related projects. Also, these
are more self-contained projects that are not part of a larger project,
and don't need to integrate with that project's existing infrastructure.

I think a text-file-based and version-controlled system is better for
larger corpora and technically versed authors/admins who want a high
degree of customizability and have the skills to implement that. If a
git and communication infrastructure exists and is used extensively
already, it can help to keep things together more easily.

(I also really didn't like how BookType worked with images, it was a
pain to just exchange one - also that the last time I used it, it didn't
support SVG.)

Hope this helps,
 Kind Regards
  Maren


Am 14.05.19 um 10:11 schrieb mick at flossmanuals.net:
> Hi there,
> 
> For the FLOSS Manual Manual update, It would be great to get people's
> experiences of when a platform like BookType that FM uses is the best
> option for an individual to use for documentation, and when other tools
> are a better fit.
> 
> Times have changed and when Adam Hyde FM started there was really
> nothing out there like it in terms of flexibility and ease of use for
> documentation. Now there are quite a few alternatives.
> 
> * https://readthedocs.org/ (in combination with https://www.sphinx-doc.org/_
> * git books - and git pages - https://www.gitbook.com/
> * some kind of static site generator using Jamstack / Hugo / Jekyll or
> similar using mark-up source files
> * other solutions
> 
> I'd be interested to know if people on this list who used to use FLOSS
> Manuals but now use something else would like to comment on the pros and
> cos. The purpose is to write a chapter that helps people evaluate if FM
> is the right place for them. Some of the factors might be...
> 
> * ease of use, pros and cos of using WYSIWYG
> * limits to version control
> * translations
> * issues around communities and particular needs / expectations
> 
> One thing, it would be great not to focus on past / current issues of
> using BookType. If you have bug reports or feature requests it would be
> great to put them here instead.
> https://gitlab.com/flossmanuals/fm_booktype
> 
> But even if there's an overlap, then please chip in!
> 
> nice one!
> 
> Mick
> 
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net - you can unsubscribe here
> 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20190516/ae1ce64f/attachment.sig>