Meeting write up: Documentation team set to work on new manual.


write-blackOn Friday afternoon we had our first meeting about the proposed new phpList manual. It was a little chaotic, but pretty much awesome! People mostly got to know the new tools and made sure they had accounts on the various websites that are needed for participation. Additionally, we hammed out our first thoughts as to who the manual is for and what info it should contain.

People in attendance

Anna, David, Elisa, Danlwc, Nikita

Resources and tools that we need
  • Everyone should all be on Documentation Team mailing list
  • Everyone needs a Community Exchange account (this site) which will give them access to the project management tool.
    • Instructions on how to use the Project Management tool are here.
  • Everyone will need a FlossManuals account on, which is where we will do our writing.
    • There is a test manual here to play with
    • The actual manual is here:

Also take a look at the current documentation listed here to get an idea of what we have right now.

We will have a fresh installation of phpList to share during writing (courtesy of Dragonrider)

WordPres project management app calendar

Our new project management tool is going to come in handy!

General idea
Who are we writing for?

“So, if we talk about end-user documentation, we should write about users needs (usage). At this moment documenation’s structure built around phpList functionality. So we need to wrote initial steps of working with program (beginners guide). And the first chapter will be overview of interface, then what users need to send a campaign (template, import users and so on), then overview of settings and configuration” – Nikita

“Who are we writing for? : newbie ? techie ? for grandma etc… I vote for newbies, up to ‘users’… leave the super high tech stuff alone for now.”  – Elisa

There was broad agreement with these statements and the idea of creating a beginners guide, aimed at users rather than system administrators or developers. However, install was also noted as a necessary chapter.

phpList meeting in IRC

We met in the phpList IRC channel on freenode

Suggested Work-flow
  • Write the chapter list
  • Each chapter should be written by one or two people
  • Then tested by two people
  • Then proofread after that
  • Then publication
  • And finally Translation
Chapter ideas

In no particular order.

  • System Overview
  • Initial Installation
  • Configuration
  • Creating your first List – intresting topic
  • Adding your first Subscribers
  • Creating a Subscribe Page
  • Creating a Template
  • Setting up E-mail Bounce Handling
  • Sending your first campaign
  • Send settings
  • Processing the Queue
  • Processing Bounces
  • Campaign Statistics?
  • Basic Troubleshooting
  • Plugins
  • About the authors
  • Templating : how creat a template, how use one and customize
    How use phpList in coordination with Piwik, Prestashop, any other big CMS ? (I can help out with Joomla!)
  • Troubleshooting
  • Installation
  • List Management
  • email 101 (basics)?
phpList piratepad

We used a piratepad to write our notes

Additional content ideas:

If we make a list of common problems we can make sure to include something about them in the correct chapter (eg, Anna suggested problem of “not having correct start date in config.php when list is older than current install” has come up a lot).

Past Experiences of Documentation

Anna: has written a few manuals before, for example this. Also has attended face-to-face manual writing sprints.

Dan: none… actually I’ve put together slides for software training (CAD for EEs), and have provided training classes for the last 20 years.

David: No manuals written as far as I can remember, but I used to be a columnist for two UK based international Monthly Magazines for several years.

Elisa: Manage Floss manuals Foundation and the french platform of Floss manuals. Facilitate documentation (booksprint). I suggest workflow for work collaboratively and for coordinate some translation into french.

Individual areas of interest and expertise

Anna: mostly done html newsletters, not very technical, but good at very basic explanations.

David: I’ve several installations of phpList which I run, along with using some to test out plugins and to help solve forum posted problems. Being helping out on the forums for years, even doing remote assistance for installs all over the world. So you do a lot of the technical side? Like installing and maintaining? Yes, I know my limits, eg Cron and php coding are my weak areas, but given sufficient info by the poster (on forums) can 95% of the time solve or at least suggest solution to problems.

Nikita: I manage some installations both by server-side and client-side. Used Hosted version in past. Big thing that I did was full translation of phpList to Russian. At that moment I’m stuck with translation of documentation because of lack of time. I do not write anything in English and more interesting in translation.

Elisa:  I try to send a campain last week with 0 success. That was my first experience of PhpList. I’m webdesigner (html + css + customisation cms) and teacher in webdesign (usability + design) and webmarketing (optimization, ranking, statistiques etc)
Dan: I know a lot about servers and email, databases and phplist… run a couple of phpList systems, for customers. created a couple virtual machines on my portable to try things out. Installed systems for other users, using cpanel, plesk, and command line. setup cron jobs. help users with troubleshooting, and some bug reports. a ‘hacker’ when it comes to php programming, i can read it, and edit, copy and paste…. I help out with answers on the forums as time allows…