Docs for tech writers - first draft posted

Hi everyone,
Thanks for all your comments so far. Our first draft for the docs for tech writers is posted at:
http://wiki.documentfoundation.org/File:Guide_for_technical_writers-draft.odt
We know there are still some inconsistencies, and we're working for the next two days to iron them out for our final version due on Wednesday. Unfortunately, we've also had to cut a few sections out from our original outline due to the length constraints of our assignment.

Let us know if you have any comments about the doc.

- Dan

I performed a very rapid copyedit of the doc and parked it on one of my inactive websites: http://swdetroit.com/Guide_for_technical_writers-draft_edit.odt, in case anybody might be interested. I did not try downloading it as a check of my uploading it correctly, but it should be OK.

The doc has some inconsistencies, where two different versions of various items were used. Perhaps, you should employ just one form throughout.

The headings employed headline-style capitalization, whereas sentence-style capitalization might be better. Personal preference, but nonfiction typically will use the latter.

Character styles should be used for bolding instead of the formatting bar (manual overrides). AFAIK, no such character styles were employed, but I only checked a few instances and did not notice any character styles.

Thanks for all the helpful comments. There is a new version of the
file uploaded that addresses some of the inconsistencies you
mentioned. We still haven't gotten to applying the character styles,
but we will before the final version of the file is uploaded tomorrow.

-Dan

You still misspelled "borders" as "boarders"... I did not check much else--just a few of the earlier copyedits.

Hi, :slight_smile:

I've downloaded the doc and, if it's OK with you, I'll proofread it
tomorrow and then upload a new version to the wiki with
corrections/comments.

David Nelson

That's ok with us. Our final due date for our class project is today, but we can certainly incorporate some changes for the final version I'll be posting in the next couple days.

Dan

Hi, :slight_smile:

That's ok with us. Our final due date for our class project is today, but we
can certainly incorporate some changes for the final version I'll be posting
in the next couple days.

Well, in which case I'll proofread it tomorrow and tell you here after
I uploaded it, and then maybe you could resume work on the proofread
version I submit?

David Nelson

That works for me David.

Dan

Hi Daniel, :slight_smile:

I proofread your document and uploaded it to the wiki [1]. I inserted
comments at various places in the doc to explain my changes, and to
make some suggestions. I slightly altered the English for what, IMHO,
would be better for an international reader base, but no major
rewrites. I reformulated some sentences, added bits, etc. Anyway,
you'll see all that.

IMHO, it's a nice draft.

If it was for the LibreOffice documentation set, I'd suggest "Power
Users Guide" for the title. That's the audience it fits, and it
doesn't have much content that makes it really specific to technical
writers.

A few ideas: maybe you could address the subject of bibliography
a bit more, for example? (Even if not in too much detail.) Same thing
for fields? Also, maybe you could cover MACROS (macro recording, if
not macro programming), and the advanced aspects of find-and-replace?
(Regular expressions is what I'm thinking of.)

Anyway, IMVHO, it's nicely written and packs a lot into a small
manual, so that more-advanced users can get up to speed quickly
without having to read large volumes of documentation.

I understand you have a size constraint to comply with. If you don't
have time or if you can't write much more (because of your project
rules), maybe I could help you develop the above suggestions. It would
make a nice little project for me, too! :slight_smile:

I, for one, will certainly pay personal attention to maintaining it in
the future, if you don't have time to work on it yourself.

Anyway, Thanks for your work. Great job, and I hope you get good
marks. You and your co-authors certainly deserve it. :slight_smile:

HTH.

[1] http://wiki.documentfoundation.org/File:Guide_for_technical_writers-draft.odt

David Nelson

David,
You may be interested in this list of topics I put together for a
proposed longer document aimed at techwriters:

http://wiki.services.openoffice.org/wiki/Documentation/Dashboard/Tutorials/Targeted

I believe Daniel and his fellow students picked a few topics from that
list, since their assignment had a 20-page limit.

--Jean

Hi Jean, :slight_smile:

You may be interested in this list of topics I put together for a
proposed longer document aimed at techwriters:

http://wiki.services.openoffice.org/wiki/Documentation/Dashboard/Tutorials/Targeted

Yes, there are lots of good suggestions of topics to cover there. I'm
going to have a think about how to further develop this guide by
Daniel et al.

David Nelson