[FM Discuss] Help, Advice, Tips for a project documentation.

[Janet Swisher]

Hi Muntek,

Welcome to the FM discussion list and congratulations on your new role
as Doc Team Leader! Writing experience is not required :-)

I think you're on the right track with dividing the doc based on roles
(devs/admins/users). I suggest that the next level of organization be
goals, and then tasks; it looks like your existing Administrators
Guide has at least some of this (e.g., Managing projects). Resist the
temptation to organize the docs around the software's features. Focus
on the users' needs. It's also a good idea to keep explanations of
concepts (and reference info) distinct from task procedures; mixing
them together gets in the way of people needing task info, and can be
missed by people looking for concept (or reference) info.

I see that you're also on the Support Team, which is good. Users don't
care about the distinction between support and documentation. They
just want to get timely answers to their questions. You might consider
creating a way to flag good answers in the forums, so that they can
later be incorporated into the documentation. Being active on the
support forums also gives you good data about the real problems,
concerns, and skill levels of users, which leads to better-focused
documentation. (Our own Anne Gentle has written a book on the
intersection of social media and documentation
<http://xmlpress.net/publications/conversation-community/>, but it's
targeted more at traditional corporate tech writers.)

And finally, if you haven't already, take a look at the FLOSS Manuals
book on running book sprints: http://en.flossmanuals.net/booksprints

--Janet

On Fri, May 14, 2010 at 10:21 AM, RedMight Muntek <Muntek at redmight.com> wrote:
> Howdy!
> I have been a heavy user of a FLOSS (GPL v2) project for several years now,
> but only recently have I become more involved. I have been pushing heavily
> for more "open-nes" and my efforts have paid off in the creation of "teams"
> to lead separate areas of development/support.
>
> Say hello to the new Documentation Team Leader :)
>
> Unfortunately I'm definitely not a writer nor a documentation expert. I have
> used some FLOSS Manuals from you guys before, and have thought them to be
> most excellent so I come here looking for help and advice.
>
> Currently the project has a hodge-podge of varying quality documentation
> spread across a wiki, a forum, and an issue tracker. I'm looking for
> suggestions and best practices on how I should go about reorganizing,
> restructuring, and creating all the current and needed stuff into a cohesive
> set of useful and consistent documentation.
>
> The Project is Redmine - http://redmine.org . We just had a meeting of team
> leaders ( http://www.redmine.org/projects/redmine/wiki/Teams ) and have
> agreed to have Book sprint in July. Prior to that still need to get things
> prepared, and some semblance of organization created. I'm looking to split
> the docs into three areas - For Developers, For Administrators, and For
> users.
>
> Any help, advice, tips, or suggestions anyone is willing to give would be
> much appreciated!
>