directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Lécharny <elecha...@gmail.com>
Subject Re: Apache documentation
Date Wed, 03 Aug 2016 19:26:24 GMT
Le 03/08/16 à 20:26, Martin Rosse a écrit :
> 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
Martin, I would not have wrote a better answer... You can *feel* the
technical writer being you ;-)

Thanks !

Mime
View raw message