Good morning all,
Not sure I can contribute anything much on the two systems Mike's
mentioned, but I've some related comments, for what they're worth:
In general I've found the present documentation to be clearly written
and formatted well, albeit (as with all documentation) it takes a little
time to get used to the writer's intentions.
I think the presentation is much better than many other project docs
I've seen. Unless there was a compelling need or evidence to change the
presentation per se I suggest it'd be a positive if something similar to
the current output format could be retained.
From an input perspective, this may be at complete odds with what I've
just said, but almost everyone will know how to fundamentally edit text
documents, whereas understanding and hand-editing XML etc is simply an
arse (well, to me it is!). So, not knowing anything about the
possibilities, a system that is as similar as possible to the way people
would do it using something like LibreOffice or similar should be the
most universally usable. Pretty much simple WYSIWYG.
From the extremely brief look I've just taken at Asciidoc it's clearly
not WYSIWYG? This may be ok for those who're used to cli/cryptic
methodologies, but that certainly isn't everyone, and it doesn't make it
easy (setting aside the 'purety' argument :-). People who may be good at
writing clear documentation may not be coders, and could be well put off
by the need to do so simply in order to present their writing. So, if
there's an intent to encourage input from others I don't see this sort
of thing to be the way forward.
Of course I could have got a hold of completely the wrong end of the
stick in which case feel free to ignore me, but if I search for 'online
WYSIWYG editor' and 'wiki WYSIWYG editor' I get quite a few results.
I've no experience with any of them, so can't provide any further
insight at this point, but perhaps someone on this list will have, and
could comment?
As for offline docs - where it's significant my personal preference is
usually for PDF because it retains the formatting that (usually) makes
documents easier to read. Long plain text docs can be difficult given
the absence of various visual cues to certain sections, and emphasis
where useful etc. For shorter things text is fine, but that's not
applicable to Guacamole IMV.
Cheers, Luke.
On 21/04/21 10:20 am, Mike Jumper wrote:
I've been thinking recently that the current guacamole-manual is not very
approachable with respect to contributions, and that members of the
community that might want to contribute to the manual may be turned off by
the complexity/unfamiliarity of DocBook and XML. It'd be nice if improving
the manual were as simple as editing a text document.
Thoughts? Asciidoc seems a common alternative that is compatible with
DocBook.
- Mike
