Documentation for WriteMonkey?

[Seth Williamson]

I found WriteMonkey only recently and was thoroughly impressed.  Best writing tool I've ever had, period.  Simply the best.

I have not found much by way of organized documentation.  True, the F1 key does seem to bring up most of what anybody would need to know.  But I have often wanted to know a little more about what a given feature means and does.

Is there a manual, per se?  I realize this might go against the Zen philosophy of the code, but I'm just wondering.

Seth Williamson

Franklin County, VA

USA

[josip]

Seth hi, thanks for your kind words. There is unfortunately no real
documentation for wm. The task is still ahead of me; so many other
seemingly more important stuff to do. You can get the best picture if
you go through release notes for each version. The features that need
additional explanation are documented in there. You'll also find many
useful info. here in this forum. You can start for example with tips
and tricks (see the top of the topic list). Or you can ask, and
somebody, if not me, will answer you.

Thanks for stopping by,
iztok

[Chris Lott]

I'm sure you've thought about creating documentation as a wiki that
users could contribute to?

c

[josip]

Actually I haven't. But it is a great idea; some kind of wiki should
be used of course. Do you have experience with wikis? What would be
the best way to get started? Using wiki on wm server? Using public
service? Wikipedia?
iztok

On Nov 19, 6:27 pm, Chris Lott <ch...@chrislott.org> wrote:
> I'm sure you've thought about creating documentation as a wiki that
> users could contribute to?
>
> c
>

[Chris Lott]

In my estimation, running a wiki on the wm server would probably be
best so you retain control and can presumably create the wiki without
advertising and without added fees. The most popular open source wikis
I've used for this kind of work are:

Mediawiki: Pros: the big one, same that runs wikipedia-- it's
recognizable, obviously in constant development, and familiar in
operation to many. Cons: database backed (could be a pro, depending on
your position), more complicated to administer, not necessarily
designed for documentation tasks

PmWiki: Pros: *very* active, responsive community and development,
file-based, a lot of plugins. Cons: plain-jane right out of the box,
getting the right mix of plugins and such to get where you want can be
a problem if you want to customize

DocuWiki: Pros: designed for documentation, file-based, active. Cons:
not easily themed, unsure of development status (presumed alive, but
it's been 6+ months since an update.

c

[Murray]

Hi Josip,

I have a lot of experience with wikis, I even once wrote a wiki engine for a client, which is where I became experienced with Markdown.

I would recommend running a wiki application on your own server, since this would give you the greatest control over the content and contributors.

M is for Murray
http://www.voodoologic.org

[josip]

Do you have a suggestion for a LAMP application?
i.

On Nov 19, 6:51 pm, Murray <planetthought...@gmail.com> wrote:
> Hi Josip,
>
> I have a lot of experience with wikis, I even once wrote a wiki engine for a
> client, which is where I became experienced with Markdown.
>
> I would recommend running a wiki application on your own server, since this
> would give you the greatest control over the content and contributors.
>

> M is for Murrayhttp://www.voodoologic.org

[josip]

Wow, that is what google wave would be good for. Almost a chat ;-)
Thanks Chris. I will give a closer look to your suggestions. I do not
think that tons of features would do us any good. More pinpointed app
would be of greater help. Maybe I should check DocuWiki first, hmmm.
Export to static windows help like file would be great too ...
i.

On Nov 19, 6:49 pm, Chris Lott <ch...@chrislott.org> wrote:
> In my estimation, running a wiki on the wm server would probably be
> best so you retain control and can presumably create the wiki without
> advertising and without added fees. The most popular open source wikis
> I've used for this kind of work are:
>
> Mediawiki: Pros: the big one, same that runs wikipedia-- it's
> recognizable, obviously in constant development, and familiar in
> operation to many. Cons: database backed (could be a pro, depending on
> your position), more complicated to administer, not necessarily
> designed for documentation tasks
>
> PmWiki: Pros: *very* active, responsive community and development,
> file-based, a lot of plugins. Cons: plain-jane right out of the box,
> getting the right mix of plugins and such to get where you want can be
> a problem if you want to customize
>
> DocuWiki: Pros: designed for documentation, file-based, active. Cons:
> not easily themed, unsure of development status (presumed alive, but
> it's been 6+ months since an update.
>
> c
>

[josip]

I just got an email:

I use WM with DocuWiki... a perfect marriage: I write without
distraction, then I put the texts directly (almost without
re-formatting) within DocuWiki.

DocuWiki has also a script to help easy installation.


Doing documentation for wm in wm. Nice ;-)
i.

[Chris Lott]

Sure... and in the case of documentation I wouldn't recommend a bloggy
CMS anyway...

c

On Thu, Nov 19, 2009 at 12:08 PM, Thor K.H. <nitro...@gmail.com> wrote:
>
> I myself have used the template system in Dokuwiki and it's pretty
> straightforward. Much, much simpler than Wordpress.

[Thor K.H.]

I myself have used the template system in Dokuwiki and it's pretty straightforward. Much, much simpler than Wordpress.

Regards,
--
Thor K.H
http://nitrolinken.net

[Murray]

Hi Josip,

Will you allow users to contribute to the documentation? I imagine we could assist in the task.

M is for Murray
http://www.voodoologic.org

[josip]

Of course, that is why wiki. Also, it would be great if a native
English speaker will moderate and edit the whole process. The docu.
should be written in real English, not my crippled one ;-).
i.

On Nov 20, 1:19 pm, Murray <planetthought...@gmail.com> wrote:
> Hi Josip,
>
> Will you allow users to contribute to the documentation? I imagine we could
> assist in the task.
>

> M is for Murrayhttp://www.voodoologic.org

>
> On Fri, Nov 20, 2009 at 08:51, Chris Lott <ch...@chrislott.org> wrote:
>
> > Sure... and in the case of documentation I wouldn't recommend a bloggy
> > CMS anyway...
>
> > c
>

[Murray]

Lol, you write better english than many native-born english speakers I know.

But will be happy to help out when the wiki is up and running.

M is for Murray
http://www.voodoologic.org

[The Captain]

Just got my hands on the program and will take notes on wiki topics
while I write. I'd be happy to contribute to this fine work!

-Ricky

On Nov 21, 9:01 am, Murray <planetthought...@gmail.com> wrote:
> Lol, you write better english than many native-born english speakers I know.
>
> But will be happy to help out when the wiki is up and running.
>

> M is for Murrayhttp://www.voodoologic.org

[josip]

I am posting the e-mail from DCStrain regarding wm documentation. He
is right!
-----

You state on your website you welcome feedback...

Tell me please; why is it that programmers spend so much time working
on a program that appears to work great ... and almost no time on
making a help file so the average person can use it without pulling
their hear out figuring it out. I don't get this.

I have hired a lot of programmers over the years and I would not hire
anyone who doesn't consider good documentation to be as important as
the application itself.

I always told them that the application and the documentation "is the
program" -- not just the application.

Is it because it is free? Do you folks think because you are providing
it for free that you don't have to spend all that time on a decent
help file?

Programmers like to program and few of them like doing the help file
for the end user. I know that, but come on my friend ... what is the
point of it all.

So you have a lot of good testimonials. Big deal. How about the people
who deleted your program because they can't figure it out.

And how about contributions? I send contributions to programmers who
write good programs but only those who have a help file as good as the
application.

I not an amateur, but it is absurd to have to go digging around to get
answers to basic questions. And I'm not going to spend much time
digging on the Internet for the answer.

Please.

I'll give a go again, but I have the distinct feeling writemonkey
won't stay on my machine for long.

Regards,
DCStrain

[Murray]

Hi Josip,

DCStrain has a valid point of view, but it's worth remembering the phrase, "You can't please all the people all the time."

For every DCStrain who will send you a terse email about the lack of documentation, there are others who enjoy discovering an application's capabilities through the process of using it, rather than reading about it.

This is not to say that help documentation doesn't have an important place (I am a programmer as well), but DCStrain appears to be ignorant that an application such as WriteMonkey must follow an evolutionary path, and that help documentation will be one of its evolutionary steps. He has simply arrived too early in WM's evolutionary process for his own comfort level. That's a pity, but I imagine he has rejected other software that had fully developed help files for other reasons. People are like that.

Personally, I would suggest that when you are ready to release a version 1.00, this would be the ideal time to also have targeted some help documentation, hopefully with the contribution of those of us who aren't daunted in the same way DCStrain is.

M is for Murray
http://www.voodoologic.org

--

You received this message because you are subscribed to the Google Groups "Writemonkey" group.
To post to this group, send email to write...@googlegroups.com.
To unsubscribe from this group, send email to writemonkey...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/writemonkey?hl=en.

[josip]

Murray, thanks for your wise and kind words ... I intend to do it
exactly as you put it in the last paragraph.
i.

On Dec 8, 12:29 pm, Murray <planetthought...@gmail.com> wrote:
> Hi Josip,
>
> DCStrain has a valid point of view, but it's worth remembering the phrase,
> "You can't please all the people all the time."
>
> For every DCStrain who will send you a terse email about the lack of

> documentation, there are others who *enjoy* discovering an application's

> capabilities through the process of using it, rather than reading about it.
>
> This is not to say that help documentation doesn't have an important place
> (I am a programmer as well), but DCStrain appears to be ignorant that an
> application such as WriteMonkey must follow an evolutionary path, and that
> help documentation will be one of its evolutionary steps. He has simply
> arrived too early in WM's evolutionary process for his own comfort level.
> That's a pity, but I imagine he has rejected other software that had fully
> developed help files for other reasons. People are like that.
>
> Personally, I would suggest that when you are ready to release a version
> 1.00, this would be the ideal time to also have targeted some help
> documentation, hopefully with the contribution of those of us who aren't
> daunted in the same way DCStrain is.
>

> M is for Murrayhttp://www.voodoologic.org

> > writemonkey...@googlegroups.com<writemonkey%2Bunsu...@googlegroups.com>
> > .

[Chris Lott]

It's all relative-- I'd much prefer continued evolution and refinement
of a fine, free product like WriteMonkey take precedence over writing
help docs. I feel a bit differently about products that I'm paying for
or that I'm selecting for site-wide corporate activity, etc.

This very community is an important part of WriteMonkey. If DCStrain
were to spend the same effort writing here that he did complaining and
explaining, he could've had many questions answered! If he'd prefer a
slower-developing or less featureful product that ha had more time
invested in documentation, there are plenty of options out there.

If/when you provide a way for users to contribute to wiki docs (or
whatever you choose), I'm sure you'll find many in the community that
you are building who will help with writing docs, even admin support
on the docs site, etc.

c

[Paolo Tramannoni]

I make my living mostly out of writing documentation for software (and
hardware). I deal everyday with texts written by software engineers. I
hope nobody will publish them as manuals for the final user!

Engineers might write well, but if they write documentation as a
second job, the quality of their writing will be comparable: second-
quality, sub-standard writing.

Employers who demand their developers to write documentations are
doing a bad service both to their custormers, and their own product.
If they hired a technical writer, and spent some time helping him/she
to revise the manuals, they would communicate all the features of
their product way better.

Paolo

[josip]

Paolo, I hope you will, when wm wiki docu project starts, give us some
guidance and advice. The users of wm and participants in this group
are writers so I am sure we will accomplish the task not only "ok" but
"cum laude".
i.