REFACTORING: website & docs

[GoogleCodeExporter]

The website needs a rethink.
Documentation too.

First, the website. I see some problems with it today:

1. Centralized on me, nobody else can update it (it's so 90's)
2. Too many pages, it should be simpler
3. Difficult to translate and keep translations updated
3.1. The website really needs to be translated?
3.2. Google translate isn't good enough?
4. Too hard to get content contributions from visitors
5. ... it don't remember now, but there's more.

Then documentation (SVN/trunk/doc):

1. They're not easy to update for non-members, being SVN centered.
2. Translations tend to keep not updated as the original document changes.
3. Docs are static, they do not evolve as the txt2tags source changes.

They are different problems, but maybe we can find a solution to fix them both?

WIKI or STATIC?
SVN or GITHUB?

The full website could be a wiki, maybe? We get easier contribution, but more 
maintenance work to undo vandalism/mistakes. Being the wiki sources in the 
txt2tags format is a bonus, but not a requirement.

Or we keep the t2t sources and static HTML files, but put them in SVN so 
anybody can edit. A cronjob could do a "svn update" periodically in the server 
to update the site. But getting contributions is still a problem since the 
visitor must be approved in Google Code before committing. In this regard, 
GitHub would be a better choice. It's more popular and easier to contribute.

COMMENTS

Comments. I would like to have them as an even easier way to user contribute. 
Some wiki systems have it. For static files, we got Disqus and IntenseDebate 
that could be added. Or even Facebook, but I know nothing about it.

DOCS CONTRIB

And for the documentation, I really would like it to be more open to 
contributions. Being it comments at the end (think PHP website) or convert them 
to wikis. Docs not updated are bad. They need to be more friendly to edits.

SHOULD WE DO A DRAMATIC CHANGE?

Maybe some docs could be obsoleted, some merged, some reformatted. And maybe 
some website pages should be documents or vice-versa.

And since we're talking about that, site and docs are all INFORMATION. Should 
they be separate things? It made sense in early 2000, but now? Maybe there 
should not be trunk/docs anymore and all information should be only online, 
live, updated? It's 2012!

CONCLUSION

I'm proud that every doc and website page is a txt2tags file. But I change all 
that for a better information center, that's live, interactive and up to date.

Please, write your opinion here in this issue.

Original issue reported on code.google.com by aureliojargas@gmail.com on 21 Dec 2011 at 11:50

[GoogleCodeExporter]

CODE: I think switching to git (github) or hg (bitbucket) definitely makes 
sense as it lowers the maintainance burden and allows for easier contribution.

DOCS: readthedocs.org seems to be the next big thing and we could easily 
convert the existing txt2tags files to restructuredtext. Being based on some 
kind of branch, contributions are easier and the docs can be automatically 
built there. I don't know about translations however, but I think sphinx in 
general supports them. I haven't tried the thing yet, maybe this would also be 
an option for documenting the txt2tags source itself.

WEBSITE: I would recommend splitting the site (like it's done at the moment) 
into one static part that can only be edited by developers via git/hg branches 
and a wiki for community contributions, recipes and comments. The wiki has to 
be made more prominent however.

Original comment by jendriks...@gmail.com on 22 Dec 2011 at 7:29

[GoogleCodeExporter]

CODE: I think that the Github Aurelio proposition is only for the doc. For the 
code, I was for a hg switch because of the superiority of DVCS over SVN, but in 
fact there is so few contributors to txt2tags that this is not a problem IRL. I 
think that the trunk commits push to move forward...
Our google code is a good tool, so I don't want to change it.

DOC: Github ? it's great, but it's git... hg is in python, like txt2tags. 
Readthedocs.org is really amazing : the quite perfect Sphinx with DVCS and Wiki 
power ! (I had this project in mind long time ago). The big problem for us is 
that the supported syntax is reST, our main competitor ^^. DVCS : GIT or HG ?

WEBSITE:
3.1 YES.
3.2 NO !
I like the actual website, I don't think it should be a wiki, but it should be 
translated. GitHub ou BitBucket -> GIT or HG ?

I think we should make a choice beetwen git and hg. I vote hg.

Original comment by fgalla...@gmail.com on 22 Dec 2011 at 9:03

[GoogleCodeExporter]

I haven't yet directly contributed to txt2tags code, but would very much like 
to do so in the future and I think a DVCS would greatly simplify this for me 
and other contributors. And BTW: google code also supports hg and git.

Github is more popular than bitbucket, but personally I prefer hg over git.

Original comment by jendriks...@gmail.com on 22 Dec 2011 at 10:29

[GoogleCodeExporter]

(sorry for the duplicated message)

Hello,

I know both svn and mercurial (hg). I think mercurial is really easy
to use when you know a bit svn.

Probably mercurial is much more than this, but in comparison to svn,
you just have to do a "hg pull, hg update, hg commit, hg push". You
can commit more often, making code easier to trace, without providing
the changes on the servers. Then you "push" the modifications for
everyone. Google code supports hg, so you can just switch to it in the
Administer>Source tab.

Git is probably good too, but I've heard it was more complicated to
use. It seems most people here (who have made their voice heard)
prefer hg.

I think the service provided by google code is good enough.

For the docs itself, I think we should definitely **never** use
something else than txt2tags for writing it.

Txt2tags is about writing documents. If we don't use it for our own
documentation, we completely loose credit.

If a product is so good that we should use it, and if it doesn't
support (yet) the txt2tags syntax, then let's write a plugin for it,
or if it doesn't allow this kind of addition, let's fork it.

When I needed a system to write and store txt2tags documents online, I
created an addition for pmwiki, which is very close to txt2tags's KISS
philosophy.

The drawback of pmwiki is it's possible to edit data only via the web
interface, we can't edit it elsewhere and manage it via svn / hg
whatever. Dokuwiki can do this though, and it could be interesting to
look toward this option. I tried to create a txt2tags plugin for
dokuwiki, I haven't succeeded so far.

An alternative would be to stay with PmWiki and use this receipe which
should do the same (I haven't tested it yet):

http://www.pmwiki.org/wiki/Cookbook/PageTopStore

I think the current wiki, even though it's not much used, could be for
users to contribute, and for working on some projects. Once it's
finished, data could be moved to the website. It's also the benefit to
stick to txt2tags syntax.

Original comment by eforg...@gmail.com on 23 Dec 2011 at 10:21

[GoogleCodeExporter]

About how the doc could be organised, I think the current doc is a bit 
disseminated into several small documents or pages on the website (for example 
Writing Books, Official Documentation, Tips & Tricks etc)

On contrary, there could be 2 main documents : 
- for example a small presentation of txt2tags with the basic ideas behind it.
- a big and complete handbook, covering most of txt2tags aspects, with clear 
parts about what is for users, what is for developpers etc)

Of course this shouldn't discourage people to create other howto and manuals on 
their homepage (if the license permit it, we could also include their creations 
in the handbook).

Because of the include possibilities, we could present this both online and 
offline, and separate the online versions into different parts, like it is now. 

The offline handbook (pdf) should also have an appealing appearance, like in a 
real book. We could even propose it on a print on demand service such as lulu. 
I'd suggest looking at this book for a potential inspiration in nice design: 
http://www.ifarchive.org/if-archive/infocom/compilers/inform6/manuals/designers_
manual_4.pdf

Original comment by eforg...@gmail.com on 23 Dec 2011 at 12:57

[GoogleCodeExporter]

I now completely approve Eric, txt2tags doc only, other markup languages aren't 
an option !

http://en.wikipedia.org/wiki/Eating_your_own_dog_food

Original comment by fgalla...@gmail.com on 3 Jan 2012 at 8:48

[GoogleCodeExporter]

Hi folks, thanks for the feedback!

I would exchange "eat your own food" for "easy to create, update, maintain, 
share, contribute" anytime. But as you are so vocal in this issue, let's focus 
in the "sources as txt2tags" solutions for now :)

About version control, I'm not searching for a SVN substitute for the docs & 
website. I'm searching for a better *workflow* that is easier for the ordinary 
user to contribute and comment. Just that. Sources are txt2tags, OK. But then 
what? How to make it easy to correct some typo? To keep updated? To read and 
share? To translate? To leave commentaries? That's my main questions.

For example, the PHP online manual. See it here:
http://php.net/manual/en/function.array-keys.php

Right after the function documentation comes the user comments, that add 
important information to the manual. Countless times when reading these pages I 
found the information I wanted at the comments. I wanted something similar to 
our docs.

At the User Guide, that would be great if users let their own examples of use 
in the %!postproc section. Or in the txt2tagsrc config section. So the User 
Guide could be the main source of information about the program, as currently 
the php.net website manual is for PHP. Comments are easy to implement in static 
HTML files using IntenseDabate, Disqus, Facebook...

Thinking about it now, maybe just adding comments to the docs solves the 
problem of easy contribution.

I liked the Eric idea of having only two documents: a quick start and a 
complete reference (book). There's also the manpage, but that's untouchable to 
avoid the UNIX Gods wrath :) But I think developer information shouldn't be at 
the book. That's a completely different scope.

The current User Guide we have is already the "book", we just need to expand 
it. And, of course, implement --split in txt2tags to avoid using HTMLDOC to 
generate the multiple HTML pages as we currently do.

Thinking about the User Guide as a book is interesting. That way we could push 
the PDF target forward to be more book-friendly, or even create an epub target.

Original comment by aureliojargas@gmail.com on 10 Jan 2012 at 1:34

[GoogleCodeExporter]

@jendrikseipp This readthedocs.org seems great! Maybe we can use it for the 
txt2tags Python code documentation.

Original comment by aureliojargas@gmail.com on 10 Jan 2012 at 1:41

[GoogleCodeExporter]

I've set up a page on the wiki about the new Manual:
http://wiki.txt2tags.org/index.php/Main/NewManualProposition

Original comment by eforg...@gmail.com on 12 Jan 2012 at 10:44

[GoogleCodeExporter]

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?

Original comment by eforg...@gmail.com on 11 May 2012 at 3:10

[GoogleCodeExporter]

Eric, I'm fine with your ideas and direction, please go ahead!

Documentation can live independent of the next version release. The more 
"alive" it is, the better. Keep improving, keep editing. No timeline or version 
constraints.

Oh, and don't hesitate to kill old content. Writing Books is a good example of 
something that maybe it's better to completely forget about.

About the current User Guide, it has lots of sections that are not so relevant 
to users. It would be a completely different doc if I would write it from 
scratch today. So, once again, feel free to nuke old junk. It won't hurt my 
feelings :)

I feel the current User Guide has so much "oh, see how t2t is freaking 
powerful" content. Self promoting text should be avoided. This is not important 
to the user. The user needs instructions, samples and cut/paste friendly code. 
The extensive reference should be at the end.

I really wish the program code and the documentation were simpler. I feel we're 
losing track of KISS.

Here's some mantras to echo in your head when updating the docs:

KISS
NUKE OLD JUNK
NOBODY READS MUCH TODAY

:)

Original comment by aureliojargas@gmail.com on 17 May 2012 at 1:42

[GoogleCodeExporter]

I was recently looking into t2t and I would like to comment about the "new-user 
experience".

1. Need an "Intro" - more below.
2. User guide is more of a language reference.
3. I didn't mind the website at all as it was nicely organised.

For the Intro the current "Markup Demo" is okay but it would be nice if it was 
more complete and had written explanations.  I think it should go 
title-t2t-result-details.  The reason is because you often have many similar 
syntax elements and you can't show all of the ins-and outs without explaining 
them but the language reference is too scary to read.  I may be able to write 
this once I get a bit more used to the language.

--------

Unrelated to the above but the vcs issue.  I would defiantly go distributed on 
a hosting site.  This allows people to clone-modify-share whether through the 
web interface (easy and social) or through patches (from those who resist 
web-interfaces) without worrying about permissions.  About bitbucket vs github 
it doesn't really matter but as was mentioned if you want Hg you need 
bitbucket.  I personally prefer git because the internals are absolutely 
beautiful and leak into the outside making it consistent and easy to use.  But, 
as I said it doesn't matter.  I also perfer bitbucket for a couple of small 
reasons but github is more popular so if you are expecting people to hear about 
your project there that might be a plus.  Also, if you choose git you could use 
the Google Code repo although I haven't tried branching and merging with it.

Someone mentioned t2t and Hg are both Python.  To be honest it doesn't really 
matter as I doubt a large part of this project will be hacking on your VCS.  
But it is kind of nice.

-----

For the website static is not bad.  A sandbox would be nice and I could 
envision a really cool interactive tutorial where you can edit the samples to 
test the quirks of the syntax.  But when it comes down to it most of the 
content is static and while you could use a wiki you could achieve much of the 
same functionality if you host the sources of the website in a DVSC repo and 
people can make pull request.  I know many other projects that do this 
successfully.  (Ex: D Programming Language)

Original comment by kevincox...@gmail.com on 26 May 2012 at 12:04

[GoogleCodeExporter]

As we could move to github, I made a patch to add txt2tags support to github 
markups.
Please support my pull request with a lot of enthusiastic comments !
https://github.com/github/markup/pull/152

Original comment by fgalla...@gmail.com on 15 Aug 2012 at 5:53