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 <ve...@aurelio.net>
À : txt2tags mailing list <txt2tags-list@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

------------------------------------------------------------------------------
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

Reply via email to