On Fri, 2011-03-25 at 20:00 +0100, Nicolas Évrard wrote:
> * 夜神 岩男 [2011-03-25 18:31 +0100]:
> >Tryton almost entirely lacks categories 1 and 2. I don't think there has
> >been much discussion yet about clearly identifying the need (or even
> >categorizing these by type) for this sort of thing just yet. Tryton is
> >used primarily by its core developers at the moment, and was until just
> >recently still in its budding phase. That being the case, Tryton is
> >replete with the 3rd sort of documentation.
>
> IMHO there is already a bit of documentation in the source code. For
> example
> http://hg2.tryton.org/modules/sale/file/f230b8f4a105/doc/index.rst is
> the file roughly explaining the sale module.
>
> I agree that this is not a newbie friendly way to access information,
> since you either have to browse our mercurial server to read it or to
> browse your installation of tryton to find it.
The reference above is excellent as a base for an administrator's guide
to that module. It really just suffers from the problems you mention
above about it not being a ready way to access documentation. The ideas
below will go a long way to resolving these issues.
> We should probably use Sphinx to generate a website with the
> information found on the docs directories.
>
> Moreover, this information is probably not directed to end users.
>
> Structuring the effort to
>
> a) create a process to publish this information on the website
> b) complete it with a more business friendly langage the information
> c) create document for end users (I suppose it must have
> screenshots and the like)
>
> is more than welcome (although I suppose point a is probably were b2ck
> is probably the best men for the job).
If b2ck can create the workspace for the project then it is only natural
for the documentation effort to live there. I didn't want to push any
support tasks to your end if you weren't ready for them. Time is a
precious commodity for us all -- but in this case I think that the
infrastructure work necessary to give a documentation project a home
will definitely bear fruit and have a huge long-term impact on the
growth and sustainability of the project.
> >But Tryton is now past its creaky beginnings and, in my opinion, ready
> >for some real world use. That means we suddenly are in desperate need of
> >a real documentation project to address the user and administrator
> >level.
>
> Earing that tryton is now ready for some real world use is always
> nice, so thank you ! ;)
Our opinion is that Tryton is ready for real use in companies that
conduct non-tech business, and this is a huge step in the process to get
Tryton broadly accepted.
We would like to thank you folks for having spent so much development
effort to get the project to a viable stage!
> Anyway, as I said, I think you're right when you're speaking about
> having a documentation project to address those needs.
>
> The problem is, as always, the free time we are able to spend on this.
> Helping to understand the problem, put in place the Sphinx website is
> something that I think we (as B2CK) can do. But I am afraid that we
> are not in a good position to write end users/administrator
> documentation. Because:
>
> a) we are not native English speakers. We can write skeleton of
> documentation but it would need a lot of proof reading.
> b) we are developers and we may lack the end user perspective to
> ask ourselves the good questions.
> c) last but not least, we do not have time for this. I am already
> late on my code reviewing duties, documentation will, as
> always, be put aside while I have other stuffs to do.
I am not very familiar with how Sphinx works, but it is something I am
entirely open to learning. If a work space can be provided that allows:
1. Easy collaboration on textual editing
2. Insertion of images (screenshots and diagrams, mainly)
3. HTML links to external resources
4. Editorial oversight so it is easy to manage a development and a
published version by the project manager
5. Easy export of documents from the editor to monolithic HTML,
paged HTML and (if possible) PDF
Then it will have all the core functionality necessary to support a
solid documentation project and documentation community.
As for your concerns:
A. We can handle proofing texts and transforming good ideas and
structure into natural English. We just need a place to start.
This will be easier than us than starting completely from
scratch anyway.
B. Dealing with end users is really our special area of focus, as
we are focusing on integration and servicing -- so any problems
with the manuals will be easy for us to identify and fill the
gaps that don't feel like gaps to you as developers.
C. This is our focus, so we will make time. Obviously there will be
some crossover with our end submitting code changes, bug
reports, etc. and the developer end being involved in some
documentation efforts, but basically I am willing to take the
management burden of a documentation project off of your
shoulders to make this effort fly.
> >You noted that "out of the box" Tryton is useless -- and it is.
>
> I kind of disagree ;). There is already a lot of cool stuffs you can
> do (but you need some formation to be able to do it).
You are right. Saying "Tryton is useless" is a bit of an overstatement.
What I meant is that Tryton, in its current form, is only useful to
people who are either already deeply familiar with Tryton or have
experience with ERP systems integration (and systems/Linux and network
administration as well).
Its a lot like having someone provide a complete machine shop for you
without any training. If you are a professional machinist then this is a
dream come true. On the other hand, if you have no machine tooling or
factory management experience but have great dreams about things you
want to build then having the machine shop without any educated people
to run it is only half of the solution.
> >One very important type of documentation lives far beyond the manual,
> >and that is in example test data, in-session tool tips, comfortable
> >templates, and core dialogues (i.e. wizards).
>
> There is already some help tooltips, they are scattered all through
> the code source. Look for the "help" keyword of fields.
In some places, yes, but often these are more focused toward helping
people understand where different data elements go and how Tryton
handles them. This is useful for builders of new modules and people
trying to track down bugs, but does not address the problems faced by an
office worker wanting to know how his input in certain fields not marked
as "required" will affect his workflow or the printed ODT output of a
form later on in a different module.
> I don't understand what you mean by "comfortable templates" and "core
> dialogues".
[LONG: Warning, this explanation is long. It is long because I think it
is extremely important to understand if Tryton is to gain much market
share.]
"Comfortable templates" means template information that is intuitive and
easy to understand. In the case of Tryton I believe it should also mean
including some skeleton information so that users can see how the ODT
output will look once they have fully populated their database with
customer, company, sales, etc. information so they can see some samples
of how real document output will look.
This is a big deal for companies trying to evaluate a complicated system
like Tryton because the amount of time required to get to the point
where some sample workflows can run their course the way they really
will when the system is in production use is considerable. In other
words, if the systems integration people in a company cannot easily show
their boss how forms will look, then they have a very hard time
convincing the boss to make a switch to the new system.
This is the number one reason why most mid-sized businesses do not use
ERP systems and instead waste millions of man-hours working inside of
non-integrated data environments such as spreasheet programs, word
processors, etc. to generate customer invoices by hand. It is very
simple for someone to create a template invoice in a word processor like
Writer or Word and show their boss, with about 10 minutes of effort, how
the invoices and logo will look and where everything will appear in
documents that will be seen by outside clients (the most important
people to any business). The fact that using separate word processors,
email clients, calendar viewers, project scheduling software,
spreadsheet programs (which require independent programming within the
spreadsheet to be really useful in any case), and accounting software
wastes untold millions of hours of office manpower and overtime is
something that is much more difficult to see and explain in the short
time span available at a company meeting.
Pretty document templates that are easy to adjust (and not mysterious to
adjust) are the easiest way to sell someone on the utility of a system
-- even if this is actually the most shallow level of performance for a
deep information management tool like Tryton.
"Core dialogues" is really a reference to the wizard functions. There
are tools to build wizards, and other tools to build workflows. They are
a bit mysterious to new administrators because there are not many
editable examples of existing basic workflows and wizards bundled with
the system to give them a comfortable headstart experimenting and
adjusting things to suit their own company's needs.
[/LONG]
> For the test data, we have tests/ directories in some modules that
> use scenarios written in .rst to test and demonstrate the capacities
> of modules. Those scenarios do not erase the database after having run
> so that you can browse it with your usual tryton client.
Some data exists and that data is very useful, it just needs to be
expanded. Most importantly, though, it must be made more obvious to new
users. By the time someone discovers this data they are usually already
well versed in how Tryton works.
> I think you're talking about something that distribution should do.
> And AFAICT debian do create a menu entry for the Tryton client.
>
> The Tryton modules are installable just like other debian packages and
> their dependencies is handled by apt, so for me everything looks fine
> for this point.
My response to this is beyond the scope of a discussion about
documentation and user friendliness... but will be very important to
discuss elsewhere if the Tryton project wants to get traction in major
business markets (and I'm assuming b2ck would love the business
exposure...?).
> You are more than welcome to help us make Tryton better. Your work on
> this issue would be a very valuable contribution to the project.
I see this project going good places.
> As I said, I am ready to help on this issue. Don't expect me to write
> 10 chapters about Tryton modules business rules but I think I can
> proof read your work.
I'll worry about writing out the 10 chapters (^.^) and incorporating
edits from others. You guys are busy with other things. I'm sure that if
I get a solid usage guide generally fleshed out that soon additional
contributors will come out of the woodwork -- the same way that coding
projects tend to attract developers once a working version gets
published (as opposed to all the projects that die in the "pre-Alpha"
proposal phase).
> Another issue on which b2ck might help is to help create the necessary
> workspace for this: automatic build of tryton documentation with
> sphinx and make it available on the website.
This would be a natural fit and keep everything in one place. I'll need
some guidance on how to get working with Sphinx and how the Tryton
website works, but those are pretty minor issues.
> We must begin the process of putting all those bit of information
> altogether in order to tell a story. But I think this should be
> discuss in separate emails.
I'll probably be contacting you tomorrow to discuss the details (unless
we have another ridiculous earthquake or something). If we flesh out a
basic outline and make sure *I* have a solid lock on how things work,
then I can take over from there and produce a user-end and
administrators' guide.
I am most familiar with how the Fedora and Red Hat project documentation
works. It is one of the best managed and most cleanly published
documentation projects around and we could learn a lot from it:
https://fedoraproject.org/wiki/DocsProject
Live drafts:
https://fedoraproject.org/wiki/Category:Draft_documentation
Published Deployment Guide:
http://docs.fedoraproject.org/en-US/Fedora/14/html/Deployment_Guide/index.html
I had actually considered running this there, but that would potentially
cut a large part of the community that is most knowledgable about Tryton
out at the beginning. (On the other hand, transferring polished Tryton
documentation commits to Fedora docs will give us a huge amount of
public exposure later, as Tryton would be a strong candidate for
inclusion in RHEL at that point. Tryton is ready for that level of
attention, in my opinion.)
> That's precisely why I think the Sphinx option is better.
> Moreover since the information reside in the module source repository
> we can have versioned website (one for 1.6, another for 1.8 and so
> on).
If using Sphinx requires commiting documentation in source file bundles,
then this could be problematic. It raises the barrier to entry later on
down the road for newcomers who want to contribute to the documentation
project but are not familiar with development tools, repository
management or the open source community. Something that is web based,
very openly available and easy to use for a non-technical user (who may,
however, be a very seasoned ERP systems administrator or user from
another ERP background like SAP) is ideal. Again, I don't know much
about Sphinx, so ease-of-use discussions are premature.
> The problem is that it requires some knowledge about mercurial and
> restructured text (but there is editors for rest and TortoiseHG make
> it very easy to use mercurial).
We'll see. I'll certainly try out whatever you recommend first. If there
are problems I'm sure we can find a suitable alternative.
> >Your thoughts (directed at everyone)? -Iwao
>
> There you are, I hope we can put some momentum on this project to make
> Tryton easier for first comers.
>
> --
> Nicolas Évrard
I'm very optimistic about this.
-Iwao
--
[email protected] mailing list
