I am of the opinion that accurate, continuously updated and improved
documentation is of critical importance to the long-term success of any
non-trivial software package, and as a New Yorker, adhere to the "broken
windows <http://en.wikipedia.org/wiki/Broken_windows_theory#New_York_City>"
theory. I also feel that FOSS developers shouldn't have to spend much time
on the documentation side of their projects, ideally limited to
developer-targeted areas where "mere mortal" community members simply don't
have the required knowledge. In particular, user-level howto's, especially
those targeting the newbie, are IMO best written by those still relatively
new to the program - obviously with more experienced members "looking over
their shoulder" to correct any inaccuracies, linking to more in-depth pages
where appropriate etc. Simple typo's, grammar fixes and stylistic
improvements should be quickly and easily done by an community member right
then and there as they are reading and notice the suboptimal content.
Personally, I've been trying to make myself useful in those few areas such
as these where I can, but have to admit feeling a bit frustrated when even
obvious and tiny corrections need to be logged to the bug tracker, where of
course they must sit in deference to higher priority demands on the
developers' time ("bump examples" cited at the bottom of this post).
For example, the time that might be spent creating and maintaining an
all-in-one Windows package would IMO be much better invested in a
centralized documentation store accessible to editing by the community
beyond the usual suspects.
May I be so bold as to suggest a specific wiki platform: DokuWiki could
serve up Leo-derived @shadow files directly - it doesn't use a database,
the wiki data store is plaintext files. It has fine-grained ACLs if that's
an issue, and you could use its version control or any VCS you like to
check out the "public edits/contributions" before incorporating them into
the "canonical" documentation shipped in the .leo files. Filesystem
directories can serve as namespaces, e.g. separating HowTos from Reference,
or user-level from developer, however you like.
IMO so many areas of the current wiki are now so out of date the project
would be better served by simply wiping it.
====================
Past docfix suggestions - note I don't presume my suggestions be adopted
wholesale, simply for the issues raised to be considered and either
implemented or rejected, rather than remaining in limbo.
http://webpages.charter.net/edreamleo/installing.html#required-and-optional-packages
still reads "Leo also requires either the Qt widget set."
and the broken link is still cited here:
http://webpages.charter.net/edreamleo/FAQ.html#how-can-i-display-graphics-in-leo
Along with the some other doc fixes I've logged here:
https://bugs.launchpad.net/leo-editor/+bug/905276
Also, search LeoDocs for "tk" and you'll find lots of now-irrelevant bits
to archive out.
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To view this discussion on the web visit
https://groups.google.com/d/msg/leo-editor/-/uu85satgb9YJ.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/leo-editor?hl=en.
