As a technical translator and writer, one of the biggest issues I encounter
-besides the obvious technical difficulties- is the quality and consistency
of the original texts and the related technical info.
For example: writing a workshop manual for a machine based on technical
data in english provided by a japanese engineer is a constant challenge, as
japanese engineers normally don't seem to like using prepositions in their
phrases. So, it's only after some engineer-harassment how the original
"port emergency generator red terminal contact box interface" gets properly
understood (that's why I'm so expensive) and written down as "interface, in
the contact box, for the red terminal coming from the port emergency
generator"... You get my point.
One usual comment about software documentation -and TW5 is not an
exception- is that its documentation is not easy to understand by
unfamiliar users.
More as a to-do list for my self than in the spirit of controversy, I'm
writing down the issues I find in the original TW documentation while
porting it to the spanish edition, in order to gradually and recursively
cope with them.
I will therefore focus on the spanish edition, refraining any other
contribution until the spanish version is up and running and I get a full
documentation snag-list to work effectively on.
My roadmap regarding TW5 documentation ideally looks like this:
- Direct translation into spanish of the documents (done by half by now,
approx.)
- Recursively adapt terms, examples and references (e.g., equivalences
in spanish for the Wikipedia links) (Done by one third now)
- Systematise original TW5 documentation.
- Replacement of direct formats by style macros in the following
cases (and the tasks related):
- Direct formats --- e.g. "this is direct format" → <<.word "this is
a style macro">> The macro only affects the graphical rendering.
- Defined concepts --- e.g. this is an emphasised ''concept'' →
this is a <<.def concept>> The macro retrieves the concept from a
glossary
and renders it consistently.
- TW components --- e.g. the ''Save'' button {{
$:/core/images/save-button
<http://tiddlywiki.com/#%24%3A%2Fcore%2Fimages%2Fsave-button>}} →
the <<.button save-wiki>>
- Anything else that needs to be consistently referred and
rendered because of importance, frequence or risk-of-error (e.g.
tiddler
tag vs tag tiddler), that both the writer and the reader could easily
be
led into mistake.
- Filling, Re-linking and reformulating missing tiddlers
- Gradual onion-rewrite of the current documentation in levels, in
accordance with:
- User level definitions (e.g. beginner: average home/office user
with some internet experience. No troubleshooting abilities, no coding
experience...)
- Usage level definitions (e.g. everyday use: create & delete
tiddlers. Minor interface tweaking, plugin import, no code hacking)
- text function definitions (read-only, read-and-execute,
translate...)
- Gradual revision of examples, external references...
- Gradual writing of the missing documentation due to:
- Release updates
- Feature upgrades
- solved issues...etc
- Cascade the documentation into the different editions,
languages...etc
This is my intention, at least. I hope it may be useful.
Yours,
Pau.
--
You received this message because you are subscribed to the Google Groups
"TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit
https://groups.google.com/d/msgid/tiddlywiki/cb84f233-b932-4c6b-bb56-ef35da56d402%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
