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

[adam]

i would also suggest that sometimes its better to write the content new
rather than push old content into shape....it can be quicker and faster
sometimes to throw away the old stuff and start from scratch

adam






On Fri, 2010-05-14 at 11:29 -0500, Janet Swisher wrote:
> 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!
> >
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net