directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Rosse <>
Subject Re: Apache documentation
Date Wed, 03 Aug 2016 18:26:45 GMT
Hi Daphne,

I am a technical writer who just started working on the Apache Directory
developer documentation, and that requires Java knowledge. It sounds like
you are looking to work on end user documentation. I have 10+ years of
experience in software documentation, so maybe I can give you some tips.

One caveat, I am relatively new to this project, and I defer to subsequent
responses from experienced committers to the project.

On to your question--I apologize if you know the following already, but
it's worth making sure so here's some up front info just in case...

Contributing to open source projects requires a lot of self-learning. These
are technical projects where your help is welcomed, but you are expected to
either have a lot of experience or are expected to be really good at
figuring out a lot of things on your own. All open source projects provide
the necessary info on how to contribute, including making doc
contributions. In other words, the answer to your question is already there
for you on the Apache Directory website already. Essentially, you can
either fix existing doc bugs or propose doc enhancements, and the tools and
info for doing so are described in detail such that in general you
shouldn't need to be posting a question like this to the developer list. If
they are not, then post and explain specifically what's lacking in that
regard. That being said, of course, your post still has some value in that
it may garner some interest, make others aware of your skills, and open the
door to some doc need info that has been percolating in some developer's
head. But generally, you should be able to move forward on your own and
find things to work on without even asking.

Also, unless you are already familiar with tools like JIRA, Maven,
Markdown, Subversion, etc., there can be a lot to learn just to be able to
understand the workflow and tools to be able to submit a documentation fix
or improvement, let alone learn the underlying software so you can revise a
user guide's contents.

But if you are up for the challenge, it is an awesome learning
experience...just don't expect much hand-holding and only ask questions to
developers as a last resort after googling, checking JIRA issues, etc.

With all that said, I am new to this project and have noticed that the
published guides are very good and thorough, but have some minor issues.
For example, if you install the software and use the guides to learn the
software, you will notice some minor doc issues. So you may want to start
doing essentially usability testing of the existing docs and noting things
to fix. You also may find existing doc issues documented in the bug
tracking tool -- JIRA. Before getting to involved in digging in to the
usability testing, you may want to find a JIRA issue (marked
"documentation") and then see if you can figure out all the mechanics of
submitting a documentation patch, and submit one successfully. Going
through that effort alone will be a great learning process.

Hope that helps,

Martin Rosse

On Wed, Aug 3, 2016 at 9:18 AM, Daphne Somkin <>

> Hi - I am a Tech Writer looking to get some documentation experience. Can
> you direct me to the part of your project that needs documentation help?
> I don't know any programming languages.
> Thank you,
> Respectfully yours,
> Daphne Somkin
> ~ 415.819.0600

View raw message