Discussion:
[t2t] I NEED YOUR OPINION: Website and docs
Aurelio Jargas
2011-12-21 23:55:56 UTC
Permalink
Hi folks,

I want to rethink the txt2tags website and docs. I want them to be
open to contributions, always updated, easy to find and read.

It's 2012 and we're still using the same static documents for the
website, manual page, user guide, quick reference, etc etc etc.

Maybe there's a better way?

Help us find! http://code.google.com/p/txt2tags/issues/detail?id=133
--
Aurelio | www.aurelio.net | @oreio
Jim Brown
2011-12-22 00:01:43 UTC
Permalink
Aurelio,
You already have the wiki---just consolidate everything there.
Jim Brown
________________________________
Sent: Wednesday, December 21, 2011 6:55 PM
Subject: [t2t] I NEED YOUR OPINION: Website and docs
Hi folks,
I want to rethink the txt2tags website and docs. I want them to be
open to contributions, always updated, easy to find and read.
It's 2012 and we're still using the same static documents for the
website, manual page, user guide, quick reference, etc etc etc.
Maybe there's a better way?
Help us find! http://code.google.com/p/txt2tags/issues/detail?id=133
--
------------------------------------------------------------------------------
Write once. Port to many.
Get the SDK and tools to simplify cross-platform app development. Create
new or port existing apps to sell to consumers worldwide. Explore the
Intel AppUpSM program developer opportunity. appdeveloper.intel.com/join
http://p.sf.net/sfu/intel-appdev
_______________________________________________
txt2tags-list mailing list
https://lists.sourceforge.net/lists/listinfo/txt2tags-list
Forgeot Eric
2012-05-11 15:13:11 UTC
Permalink
With all the new exciting additions to the current txt2tags trunk, it should probably be OK to release a new version soon (2.7).

Probably there are a few bugs to fix or some improvement to make, but this could also be left to the 2.8 release.

I'd like to discuss the documentation. Should it be left as it is in the current state for the next release, or should we improve it so it could be more user-friendly?

By user-friendly, I mean the knowledge base about txt2tags is currently quite fragmented:

User Guide, Writing Books (which is getting quite old), How to add a new target, and all the various tips we have.

I like the idea of having everything in one whole big reference book.

But there should also be several levels for users: at the beginning, basic things we can do with txt2tags, and at the end, advanced tips for developpers and full descriptions.

For example the current user guide is displaying an exhaustive descriptions of all the targets at the very beginning (3rd chapter: supported targets). Are many people still using Lout, Magic Point, Page Maker? I find it a bit confusing to talk about this to the reader when they start reading the documentation. Of course this should be mentionned, but I was thinking to something like :

"With txt2tags you can convert to popular formats on Internet (html, dokuwiki, markdown,  spip...) and to the document markup language LaTeX. You can also convert to several other formats which are described in Chapter 12 (-> direct link to this chapter, with the supported targets chapter as it is now: http://txt2tags.org/userguide/SupportedTargets.html)"

It means a complete reorganisation of the user guide. I'd like to help, but I don't want to take the initiative myself and begin this work, if others (and in particular Aurelio) don't like this direction.

Here are some work in progress for such documents:
http://wiki.txt2tags.org/index.php/Main/NewManualProposition#toc3
http://wiki.txt2tags.org/uploads/handbook.pdf
http://wiki.txt2tags.org/uploads/handbook.html
http://wiki.txt2tags.org/uploads/handbook.epub

It's quite indigest and messy at the moment, because it was quickly generated from the current doc, doing some dirty search and replace for uniformising everything. (and I didn't reorder the user manual at the moment)

What do you think?




________________________________
De : Aurelio Jargas <***@aurelio.net>
À : txt2tags mailing list <txt2tags-***@lists.sourceforge.net>; txt2tags-***@googlegroups.com
Envoyé le : Jeudi 22 décembre 2011 0h55
Objet : [t2t] I NEED YOUR OPINION: Website and docs

Hi folks,

I want to rethink the txt2tags website and docs. I want them to be
open to contributions, always updated, easy to find and read.

It's 2012 and we're still using the same static documents for the
website, manual page, user guide, quick reference, etc etc etc.

Maybe there's a better way?

Help us find! http://code.google.com/p/txt2tags/issues/detail?id=133
--
Aurelio | www.aurelio.net | @oreio
Jendrik Seipp
2012-05-16 14:09:33 UTC
Permalink
Hi,

it's good to hear that a new version might be coming out soon. I would
like to get some patches in before the new version is released though.
I'll attach them to the appropriate bug reports.

Cheers,
Jendrik
Post by Forgeot Eric
With all the new exciting additions to the current txt2tags trunk, it
should probably be OK to release a new version soon (2.7).
Probably there are a few bugs to fix or some improvement to make, but
this could also be left to the 2.8 release.
I'd like to discuss the documentation. Should it be left as it is in
the current state for the next release, or should we improve it so it
could be more user-friendly?
By user-friendly, I mean the knowledge base about txt2tags is
User Guide, Writing Books (which is getting quite old), How to add a
new target, and all the various tips we have.
I like the idea of having everything in one whole big reference book.
But there should also be several levels for users: at the beginning,
basic things we can do with txt2tags, and at the end, advanced tips
for developpers and full descriptions.
For example the current user guide is displaying an exhaustive
supported targets). Are many people still using Lout, Magic Point,
Page Maker? I find it a bit confusing to talk about this to the reader
when they start reading the documentation. Of course this should be
"With txt2tags you can convert to popular formats on Internet (html,
dokuwiki, markdown, spip...) and to the document markup language
LaTeX. You can also convert to several other formats which are
described in Chapter 12 (-> direct link to this chapter, with the
http://txt2tags.org/userguide/SupportedTargets.html)"
It means a complete reorganisation of the user guide. I'd like to
help, but I don't want to take the initiative myself and begin this
work, if others (and in particular Aurelio) don't like this direction.
http://wiki.txt2tags.org/index.php/Main/NewManualProposition#toc3
http://wiki.txt2tags.org/uploads/handbook.pdf
http://wiki.txt2tags.org/uploads/handbook.html
http://wiki.txt2tags.org/uploads/handbook.epub
It's quite indigest and messy at the moment, because it was quickly
generated from the current doc, doing some dirty search and replace
for uniformising everything. (and I didn't reorder the user manual at
the moment)
What do you think?
------------------------------------------------------------------------
*Envoyé le :* Jeudi 22 décembre 2011 0h55
*Objet :* [t2t] I NEED YOUR OPINION: Website and docs
Hi folks,
I want to rethink the txt2tags website and docs. I want them to be
open to contributions, always updated, easy to find and read.
It's 2012 and we're still using the same static documents for the
website, manual page, user guide, quick reference, etc etc etc.
Maybe there's a better way?
Help us find! http://code.google.com/p/txt2tags/issues/detail?id=133
--
------------------------------------------------------------------------------
Write once. Port to many.
Get the SDK and tools to simplify cross-platform app development. Create
new or port existing apps to sell to consumers worldwide. Explore the
Intel AppUpSM program developer opportunity. appdeveloper.intel.com/join
http://p.sf.net/sfu/intel-appdev
_______________________________________________
txt2tags-list mailing list
https://lists.sourceforge.net/lists/listinfo/txt2tags-list
------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats.http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
_______________________________________________
txt2tags-list mailing list
https://lists.sourceforge.net/lists/listinfo/txt2tags-list
Florent Gallaire
2012-05-17 03:37:12 UTC
Permalink
it's good to hear that a new version might be coming out soon. I would like
to get some patches in before the new version is released though. I'll
attach them to the appropriate bug reports.
Everybody would be happy of a "coming soon" release, but txt2tags
really needs a lot of Aurelio's work to be released, and unfortunately
he isn't currently available.

There's some design, new option and option name decisions Aurelio is
the only one who can do.

Personnally, I have done a lot of new targets so I have some fixes to
do on my TODO list.

Florent
--
FLOSS Engineer & Lawyer
Loading...